Making Amendments with a Markup Language
Page written by David Gibson
Click/Tap a link or scroll on down.
Introduction
In general, the BCRA web pages are not suitable for editing by 'untrained' staff because
they have not been designed with that in mind. Thus, unlike blogs, bulletin boards and the like,
they use 'raw' HTML code interspersed with PHP scripting, JavaScript and CSS, and would not be
comprehensible to non-experts.
I am experimenting with a method of allowing BCRA officers to make small changes to web
pages themselves. Some knowledge of coding will still be advantageous, but for small corrections
like updates to sentences and paragraphs of text, that might not be necessary. This facility has
to be specifically added to each webpage so, for now, it is just on a few pages. The procedures
are outlined below.
Pages Available for Editing
At present, this is limited to the pages for BCRA Information,
Charity Policies, Biographies
of BCRA Trustees
The page Field Meetings Guidelines can also be
edited, but follows an earlier implementation of the markup process.
Procedures
To edit a page you need to use a text editor such as Microsoft Word or
Textpad. You do not need an HTML editor. In summary, the
procedure is
- Go to the last 'chapter' on one of the above-listed pages, which is titled Staff
Information or something similar.
- Click on the link to Download a plain-text version, which will open up a new page
containing the markup data.
- Select all the text (ctrl-a, ctrl-c) and paste it into your editor.
- The text contains an HTML-like markup, as explained below. Make your changes, taking
care not to include any incorrect mark-up, as far as you are able.
- Email the file to the website editor who will run it through a verification program and
then upload it.
- In due course you will able to do the verification and uploading exercise
yourself. However, there is no point in my writing code to achieve that if the scheme does not
have frequent use.
HTML-Like Markup
If you post regularly to BB-style forums, such as the BCRA News Forum or UKcaving.com you might be familiar with BBcode, which is a
simplified subset of HTML markup. It should not be a big step to go from using BBcode to being
able to read HTML – Im not asking you to write HTML, just to be able to read
it with an adaquate level of understanding. The main points to remember are...
- The so-called HTML-like markup I am providing for you to edit is 'real' HTML but
with the < and > angle brackets replaced by square brackets [ and
]. That is so that you can read the file into a word-processing application like Word without
it trying to interpret the text as HTML, and messing everything up.
- Your downloaded file is only the 'core' of the web page. There is a lot of preamble and
post-amble that is added to create a properly-constructed full web page, as displayed on your
screen.
- In this type of markup file, so-called 'white-space' is not significant. You cannot
format your text using spaces, tabs or carriage returns because they will be ignored. If you want
to do that sort of thing you will need to learn some HTML or explain to the website editor what
you want to achieve.
- However, if you just want to make a spelling correction, or to
change a sentence, those minor edits are easy. You can add entire paragraphs but you must
indicate the start and end of the text with a pair of paragraph markup tags, [p]Like
this[/p].
- If you dont know how to do something, you can write a note to
the website editor, like please put a link to mydocument.doc here or please use
my photo here.
There are some rules about the use of characters...
- You must not use the characters < or > in your text.
- You must only use [ and ] to mark the position of HTML tags. If you want
to use those as visible characters you must 'escape' them by writing them as double characters,
i.e. [[ and ]].
- Strictly speaking, you are limited to a simple ascii character set, with all other
characters needing to be replaced by so-called HTML entities. If you know how to do that,
great; but if you dont, just carry on anyway and your text will be sanitised when the website
editor processes it.
Expert Editing
If you understand HTML, you can use an HTML editor to construct your text. But...
- You will need to convert all the square brackets to angle brackets and then
un-escape << and >> combinations to [[ and ]]. This is
not as straightforward as it might seem. After editing you will need to do the reverse
exercise.
- Alternatively, ask the website editor to supply the phtml file for the page you
want to edit.
- You will need to supply any CSS files that you require – or use embedded
style-sheets.
Technical Notes
The HTML pages for which this process is implemented have a chapter at the bottom that
explains how to edit them. This comes from the file markup_notes.html and is merged into the HTML using the
new_include_div() PHP function from common.php. That requires the name of the data
file to be passed manually (without its file extension) as an argument to the function.
The HTML pages incorporate the data file via paste_html() from
paste_html.php. The process in paste_html() does ...
- If the file page_data.phtml does not exist then proceed to create it from
the txp file
- But if that doesnt exist then die()
then...
- If the file page_data.txp does not exist then proceed to create it from
the phtml file
then...
- Check that the phtml and txp files have similar timestamps. If not, issue
a warning. This test means that the page must be loaded and executed very soon after the file
creation date. Currently, $time_mismatch in paste_html() is set to ten minutes,
- Check that the phtml contains no BODY tag. If it does then issue a warning.
- Iincorporate the phtml file in the page output.
This means that ...
- Fresh edits can be applied to either the txp or the phtml files
- But the file not being edited must be deleted so that it is
re-created
- The phtml file must be edited down from HTML if it is edited in an HTML
editor.
