mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-12-04 23:52:23 +00:00
161 lines
12 KiB
HTML
161 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>CUCC Expedition Handbook: editing the handbook</title>
|
|
<link rel="stylesheet" type="text/css" href="../css/main2.css" />
|
|
</head>
|
|
<body>
|
|
<h2 id="tophead">CUCC Expedition Manuals - Editing the Handbook</h2>
|
|
<h1>Editing the Handbook (1)</h1>
|
|
|
|
<h2>Handbook editing manual</h2>
|
|
|
|
<p>These pages are for cavers wanting to:
|
|
<ol>
|
|
<li>quickly edit a correction using "Edit this Page", or
|
|
<li>edit several pages while sitting at the <em>expo laptop</em>
|
|
<li>edit several pages using their own laptop
|
|
</ol>
|
|
|
|
<h3 id="editthispage">"Edit this page"</h3>
|
|
|
|
<p>You can update a single webpage
|
|
online via a browser. This is best for urgent edits to a single page, e.g.
|
|
if the emergency phone at top-camp has to use a new SIM with a different phone number.
|
|
<p>You can edit web pages without installing any software or doing any configuration. It even works if your laptop is a Mac.
|
|
To use it you need to <a href="/accounts/login/">log in to troggle</a> using the well-known "cavey:beery" password. You generally only need to do this once.
|
|
|
|
<p>When you are a logged-on user you will see "Edit this page" at the bottom of the menu on the top-left of this page. It appears on
|
|
nearly all pages in this website. If you click on it you will be able to edit the content of the page.
|
|
<img class="onright" alt="gosser bier" src="../i/editthispage.jpg" />
|
|
|
|
<p>The image shows what it looks like when editing the "bierbook" page. There is a menu bar along the top of the panel where you can select the usual word-processing commands to make text <b>bold</b> or <em>italic</em> and to select syles such as headings or plain text.
|
|
|
|
<p>After editing the page you save your work by clicking on the "Submit" button at the bottom (see it at the bottom-left of the image).
|
|
<p>There is nothing to stop you editing lots of pages by this method but you will find it extremely tedious. It is especially tedious creating the links between pages.
|
|
|
|
<p><b>Footnote:</b> Currently this process does not properly tidy up after itself. Everyone can see your new edited page on the website immediately but you will need to ask a nerd to finish the process to make sure that your changes become persistent and don't get overwritten. [See the explanation at <a href="#tidy">the bottom of this page</a> if you want to know more.]
|
|
|
|
<h3 id="auto">Autogenerated pages</h3>
|
|
<p>Some key sections of the online webpages are autogenerated from cave survey data
|
|
so you cannot use "Edit this page". These pages will not show "Edit this page" in the top-left menu even when you are logged in. If you need to change any of these you will need to <a href="manual.html">correct the underlying cave survey data</a></p>
|
|
<p>Some pages are not editable because the file permissions are set to read-only. This may be a mistake and you should consult a nerd to get it fixed.
|
|
|
|
<p>In either case, instead of "Edit this page" it will say "This page not editable" at the bottom of the menu.
|
|
|
|
<h3>Creating New Pages</h3>
|
|
<p>If you type in the name of a new webapge into the address bar of your browser, e.g. <a href="http://expo.survex.com/handbook/festering/spa.html">http://expo.survex.com/handbook/festering/spa.html</a> (e.g. if you want to document how to find a hot-tub in Altaussee) then troggle will offer to create the page for you. Just click on the blue text that says "Create this page":<br />
|
|
<img src="../i/createpage.jpg"/>
|
|
<p>Then once created, you can edit it the same way that you edit a pre-existing page.
|
|
|
|
<h3>Linking in New Pages</h3>
|
|
<p>You link your new page into the handbook by editing another page in which you want to create a link. For example if you have created a new page describing your wonderful new sleeping bag/hammock technique, then you might want to add a link in to <a href="../kitlist.html">Expo Personal Gear List</a>. Unfortunately the "create link" icon (a picture of 3 links of a chain) is disabled in the on-line editor so you would have to click on the HTML icon and insert the link by editing the HTML directly using an <em><a href="filename"></em> tag. See <a href="#images">Images: Relative and Absolute URLs</a> below for how to structure the URLs in the <var>href</var> attribute.
|
|
|
|
<h3 id="conventions">Conventions</h3>
|
|
This covers all files and names, not just just the handbook pages. Other parts of the handbook guidance for logbooks, cave description writeups, entrance decription text and everything else redirect here.
|
|
|
|
<h4>Encoding</h4>
|
|
<ul>
|
|
<li>We specify that pages are encoded using <a href="https://www.w3schools.com/charsets/ref_html_utf8.asp">UTF-8</a> for all content.
|
|
<li>We are using <a href="https://www.w3schools.com/html/html5_intro.asp">HTML5</a> and
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/CSS">CSS3</a> but a great many pages still use obsolescent tags such as <font>. These are being removed whenever a page is edited.
|
|
<li>All the pages use a single CSS stylesheet <a href="/css/main2.css">/css/main2.css</a>.
|
|
<li>We do not use any javascript framework: just HTML and CSS. You may come across historic references to jquery but this is not used.
|
|
<li>When editing webpages, use <a href="https://www.freeformatter.com/html-entities.html">HTML entities</a> for characters with umlauts, e.g. <var>&ouml;</var> for ö.
|
|
<li><em>Only</em> use a <a href="https://en.wikipedia.org/wiki/UTF-8#Encoding_process">UTF-8 encoding</a> if there is no HTML entity available, e.g. biohazard: <span style='font-size:30px;'>☣</span> which is written as <var> &#9763;</var>
|
|
</ul>
|
|
<h4>Automated formatting</h4>
|
|
<ul>
|
|
<li>When any .html page is loaded by troggle it replaces all the <em> <head>...</head> </em> material with the expo standard header. So don't put anything in the header of any page you edit as it will be ignored. This is also where troggle inserts the <a href="/css/main2.css">/css/main2.css</a> standard stylesheet.
|
|
<li>On loading a .html page troggle also inserts a standard menu - normally visible to the top left of the page. This is not inserted if the .html page has its own menu: <em> <div id="menu"><ul id="links"> ... various <li>items .. </ul></div></em>
|
|
<li>If you add the header line
|
|
<em><meta name="keywords" content="NOEDIT"></em>
|
|
it will be stripped out by troggle when it replaces the header, but it will notice it and will not insert "Edit this page" at the end of the inserted menu.
|
|
</ul>
|
|
<h4>Filenames</h4>
|
|
<ul>
|
|
<li>No spaces in filenames. Use underscores or hyphens.
|
|
<li>No filenames starting with "-" or "!" (Mac users beware)
|
|
<lI>All filenames to start with an alphabetic letter.
|
|
<li>All filenames to be in lower case, must not use umlauts, must not have extra full-stops in the name.
|
|
<li>Don't use capitals in any sort of identifier. If you have to, make _sure_ that they are used exactly the same everywhere.
|
|
Otherwise it's easy to make pages that work on Windows, but which don't on Linux.
|
|
<li>When you use "Edit this page" you are editing on the server which is a Linux machine.
|
|
<li> Never create two files spelt the same except for capitalisation. They will overwrite each other if edited on a Windows machine <em>without any warning</em>. This is particularly a problem for the filenames generated on phones for photographs.
|
|
|
|
</ul>
|
|
<h4 id="images">Images: Relative and Absolute URLs</h4>
|
|
<ul>
|
|
<li>Older parts of the website have sub-folders "i/", "l/", and "t/" holding respectively<br />
|
|
i/ - the image file at full resolution (600px width usually)</br>
|
|
l/ - an html file which displays the full image with a caption and some description</br>
|
|
t/ - a thumbnail image which is usually used inside an <a> tag to link to the l/ html file.
|
|
</ul>
|
|
|
|
<p>When creating figures use one of these two constructions. The first with "rooted" URLs beginning with a "/":</p>
|
|
<code><pre>
|
|
<figure class="onright">
|
|
<a href="/piclinks/typing.htm"><img src="/images/typing.jpg"></a>
|
|
<br><figcaption>Tony Rooke at computer in 1991 - in the old potato hut</figcaption>
|
|
</figure></pre></code>
|
|
or, with "relative" URLs, where the URL does not start with a "/":
|
|
<code><pre>
|
|
<figure class="onleft">
|
|
<a href="../l/hut-cables.html"><img width=200 src="../i/acer-blue-aspire-one-netbook.jpg"></a>
|
|
<br><figcaption>AA1 netbook<br /> sits high up out of reach<br />
|
|
(ours is less shiny)</figcaption>
|
|
</figure>
|
|
</pre></code>
|
|
<ul>
|
|
<li>"Rooted" URLs will work werever your fragment of HTML ends up. This root is the always the root of the <var>:expoweb:</var> repo, i.e. <var>/home/expo/expoweb/</var>.
|
|
<li>"Relative" URLs will be relative to wherever the webpage <em>is being viewed from</em> as located in the published
|
|
strcuture. This is often not where you think it is (especially for individual logbook entries and cave descriptions) but for handbook pages it is straightforward: you can see the location in the browser URL bar and for this page it is in the folder <var>"/handbook/computing/"</var>.
|
|
</ul>
|
|
|
|
|
|
|
|
<p>
|
|
P.S. In older pages that have not been updated recently, you may see this archaic form:</p>
|
|
<code><pre>
|
|
<a href="/years/2018/logbook.html#t2018-08-03w"><img src="i/logbookpage.jpg" class="onright"></a>
|
|
</pre></code>
|
|
Where the <var>class="onright"</var> attribute is set on the IMG tag and not on the FIGURE tag or an enclosing DIV tag. If you find one of those in a page you are editing, please update it to use the current <figure> and <figcaption> structure. [Note the mixed URLs in this example, one is absolute and one is relative: this is not a recommended style.]
|
|
|
|
|
|
<hr />
|
|
<h3 id="tidy">Tidying up and committing the edits</h3>
|
|
<p>'Edit This Page' edits the file served on the web, saves it, adds it to the list of proposed git updates, then finally does the git 'commit' on the server. Things can go wrong at each step of the process.
|
|
|
|
<p>Specific error message pages are produced if the file cannot be saved (usually a permissions error), if it cannot be added to git's list, or if the git commit fails (which would be due to a merge failure on a previous commit attempt).
|
|
|
|
<p>If the version control commit fails, your edits will be saved and you will see them on the
|
|
website but <em>they will be lost later</em> if you do not get a nerd to fix the version control
|
|
<a href="../computing/repos.html">repository</a> properly.
|
|
|
|
<p>To properly finish the job you need to get a nerd to
|
|
<ul>
|
|
<li>Look at the current git log and status on the server, i.e. at
|
|
<a href="/repositories/expoweb/.git/log/">expoweb repo</a>
|
|
<li>
|
|
ssh into expo@expo.survex.com from a machine already configured to do this
|
|
<li>cd to the directory containing the repo you want, i.e. "cd expoweb" for the handbook, which takes you to /home/expo/expoweb
|
|
<li>Run "<a href="https://git-scm.com/book/en/v2/Getting-Started-Getting-Help">git status</a>" (to check what
|
|
changes are pending),
|
|
<li>then "<a href="https://git-scm.com/book/en/v2/Getting-Started-Getting-Help">git add</a> <em>filename</em>" to stage the page you have just edited.
|
|
<li>then DO NOT just run '<a href="https://git-scm.com/book/en/v2/Getting-Started-Getting-Help">
|
|
git commit</a>' unless you know how <em>emacs</em> works as it would dump
|
|
you into an emacs editing window (C-x C-C is the way to exit emacs). Instead, use the "-m" option:
|
|
<code>git commit -m "changed topcamp phone number - myName" </code>
|
|
which submits the obligatory comment with the commit operation. You should write something informative and brief about your changes between the quotation marks and also give your full name.
|
|
</ul>
|
|
<p>The same 'save/git-add/git-commit' process happens when uploading drawings files or when editing survex files online.
|
|
<hr />
|
|
<p>Go on to <a href="hbmanual2.html">Editing several pages</a><br />
|
|
Return to <a href="onlinesystems.html">Online systems overview</a>
|
|
|
|
|
|
<hr /></body>
|
|
</html>
|
|
|