<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Handbook - survex - Cave Description</title>
<link rel="stylesheet" type="text/css" href="/css/main2.css" />
</head>
<body>
<h2 id="tophead">CUCC Expedition Handbook - Cave Description</h2>
<h1>Adding Cave Descriptions</h1>
<h2>Great, I have discovered a new cave...</h2>
<p>If you have not come to this page from the sequence starting at <a href="newcave.html">Starting a New Cave"</a> then go and read that first.

<div style="width:100%;height:50px;background:#C8E1E2" align="center"> 
This page outlines step 8 of the survey production process. Each step is documented separately.<br />
    <!-- Yes we need some proper context-marking here, breadcrumb trails or something. 
        Maybe a colour scheme for just this sequence of pages
    -->
<a href="newcave.html">1</a>
 - <a href="newwallet.html">2</a>
 - <a href="newsurvex.html">3</a>
 - <a href="drawup.htm">4</a>
 - <a href="newrig.html">5</a>
 - <a href="caveentry.html">6</a>
 - <a href="ententry.html">7</a>
 - <a href="cavedescription.html">8</a>
</div>
<h2>In the survex file</h2>

<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
<div >
<figure>
<a href="/survexfile/caves-1623/290/toto_to_crystalcrumble.svx">
<img src="../i/svx-cave-descript.jpg"></a>
<figcaption style="font-variant-caps: small-caps;">
<em>Description of FischGesicht trip on 2018.07.24 (click to open in editor)</em>
</figcaption>
</figure>
</div>

<p>Cave descriptions are written at the end of the survex block - between <var>*begin</var> and 
<var>*end</var> statements. Conventionally just after 
<a href="qmentry.html">the QMs</a> and before the <var>*end</var> .

<p>The description is written as a single long line of text. In the online editor it is wrapped to fit the window.
<code>
;------------<br />
;Cave description  ;(leave commented-out)<br />
; See 2017 description for details of GSH up to the 'p50'. 
Briefly, on the way to couldashouldawoulda a 22 m entrance crawl from the 
surface leads to a climb down and a junction. Left leads to easy c
rawling passage for a short distance, then another junction where 
traversing over a shallow hole and down a stooping-height sandy 
passage to a sharp left turn and a sandy, easy 'squeeze' leading to a 
straighforward p10. 
    </code>
[from <a href="/survexfile/caves-1623/290/couldashouldawoulda_to_bathdodgersbypass.svx"><em>couldashouldawoulda_to_bathdodgersbypass.svx</em></a>]
</p>
<p>You can have several lines of description, as you can see if you follow the link above,  but each one must be 
prefixed with a semi-colon otherwise the survex software will complain.

<p style="margin:4%">
<em>Technical Note:</em> The syntax for a Cave Description, both the title and the text includes a leading semi-colon. 
So it is syntactically a "comment" so far as <a href="https://survex.com/docs/manual/datafile.htm">the survex software</a>
is concerned. 


<h2>In the Cave Definition file</h2>
<p>When you look at a cave listed in the list on the "<a href="/caves/">Caves"</a>" page, such as <a 
href="/1623/290/290.html">/1623/290/290.html</a>, and you click on "Edit this cave" in the left-hand menu when you are 
logged-on, you will see the Cave Registration <a href="/1623-290_cave_edit/">editing and update form</a>. 
All the cave description you read on the Cave 
page is set in the text box "Underground description" on the form in 
<a href="https://www.w3schools.com/html/html_paragraphs.asp">HTML</a>.
<p>So for an existing cave, where someone has already done the 
<a href="caveentry.html">initial cave registration process</a>, you can easily add in your description of your new 
passage by cutting and pasting from your survex file, e.g.
<a href="/survexfile/caves-1623/2017-cucc-28/toto_to_crystalcrumble.svx">toto_to_crystalcrumble.svx</a> into the
end of the text in the "Underground description" text box.
<p>You can drag the corners of the "Underground description" text box on the cave registration form to make it easier to edit the HTML.
Just separate the paragraphs with &lt;P&gt; codes and it will work. (You don't need the semi-colons any more.)

<p style="margin:4%">
<em>Technical Note:</em> The information in the cave registration form is saved to the server as a file, which is 
committed to the version control system automatically,  as 
well as being registered in the online database used by the website publication software. If you are a nerd with a 
<a href="../computing/bulkupdatelaptop.html#basic"><var>bulk update laptop</var></a>, you can edit the file directly. 
For Fischgesicht (originally 2017-CUCC-28 and now 1623/290), this is in the 
<var>:expoweb:</var> repo, in <var>/cave_data/1623-290.html</var>, but you will have to manage the git commit process yourself.

<p>Fischgesicht currently (pre-2023 expo) has 25 survex files (listed as <a href="/survexfile/2017-cucc-28">2017-cucc-28</a>, <a href="/survexfile/290">290</a>
  or <a href="/survexfile/caves-1623/290/290.svx">290 survexfile</a> ). You could do a useful job by
checking all those survex files to see if the cave description in them has already been copied into the cave registration form 
"Underground description" text box.

<h3>More complex caves</h3>
<p>Fischgesicht currently has only one cave description file. Older, more complex caves such as Balkonh&ouml;hle 
have the cave description separated out into several HTML files. The field of the cave registration form "Description file", 
which was blank for Fischgesicht, has a filename in it on the Balkonh&ouml;hle form: "<var>1623/264/ent.html</var>"
 which is in the <var>:expoweb:</var> repo folder. 
 <p>Unfortunately, you cannot (yet) use the "Edit This Page" capability to edit those
 webpages from any web browser and you will need to use the <var>expo laptop</var> in the potato hut to play 
 with the files directly. (Or elevate yourself to nerd status and configure your own laptop as a 
 <a href="../computing/basiclaptop.html#basic"><var>basic expo laptop</var></a> yourself.)

<h3>Adding photographs to cave descriptions</h3>
<p>Cave Schwa H&ouml;hle 1623/81 is a simple cave and if you look at its 
<a href="/1623-81_cave_edit/">cave registration form online</a>
and look in the "Survey" field, you will see that the "Survey" text box contains the HTML code for several images of cave surveys 
with relative filepaths like this: 
<br><pre><code>&lt;img src="../others/82_area_plan.png" alt="Survey" /&gt;
</code></pre>
These are relative to where the cave description will be published, which is specified in the 
"URL" field. 
<p>The reason why they are relative to the <em>published</em> webpage is that it is your own web browser which is interpreting 
the &lt;IMG&gt; link, and it will use that to ask the server for the image.

<p>Now it is a good idea to go and read the "Edit Cave Form" part of the handbook page 
<a href="caveentry.html#editcave">Creating a new cave in the online system</a> which compares the two caves 171 and 172 and how their photograph
data is stored slightly differently.

<p>The "URL" field has a helpful hint next to it in square brackets: [1623/000/000] to remind you of the right format
when you are creating a new cave. For this cave 
the URL is set to <var>1623/264/264.html</var>. [Note that despite having ".html" at the end of it, this is not a real file: it is generated by the website publication software to contain
all these bits of information.]
<p> The <em>real</em> file holding the cave description is in the "Description file" field which says
<var>1623/264/ent.html</var> and is in the <var>:expoweb:</var> repo.

<h4>Summary</h4>
<p>So using just a web browser you can edit the HTML for the top-level cave description, and you can add in links to 
photos - using the "image" button next to the cave description field [** better documentation of this needed, capability added by Martin Green in 2022]
<p>It is instructive to look at the cave registration form for Balkonh&ouml;hle at the same time as 
reading the published cave description in another browser window.
You will see how the different parts are assembled into one overall description. You will need to know this before 
you can edit the HTML of complex caves directly.

<hr />
Return to  "<a href="newsurvex.html">Survey handbook - survex format</a>"<br>

Return to  "<a href="qmentry.html">QMs (Question Marks)</a>"<br>

Return to  "<a href="newwallet.html">New survey wallet</a>"

<hr /></body>
</html>