=============================================================================
XMLMan - Generate RISC OS documentation from XML                 Version ----

(C) Stephen Fryatt, 2018-2024                                   18 April 2025
=============================================================================

Contents
--------

  1. Licence
  2. Introduction
  3. Documents
  4. HTML output
  5. Version History
  Updates and Contacting Me

1. Licence
----------

  XMLMan is licensed under the EUPL, Version 1.2 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl.

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "*as is*" basis,
  *without warranties or conditions of any kind*, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for XMLMan can be found alongside this binary download, at
  https://github.com/steve-fryatt/XMLMan.

2. Introduction
---------------

  XMLMan is a tool for generating documentation in a variety of formats from
  an XML source. It is written in C, and can be compiled to run on platforms
  other than RISC OS.

3. Documents
------------

  An XMLMan document consists of one or more XML files. They are notionally
  in UTF-8 encoding, although users creating files on RISC OS can avoid this
  by sticking to ASCII and using entities for the "top-bit" characters. This
  approach also makes it easier to store the files in source code management
  systems on other platforms.

  The files mostly follow the standard XML syntax rules, which are as
  follows.

  * Tags are enclosed in < and > angle brackets, and use lower case.
  * Attribute names are in lower case, and their values are strings enclosed
    in double-quotes.
  * Entities are lower case text enclosed by & and a semicolon. A subset of
    the HTML 5 entities are supported.
  * The <, >, " and & characters are reserved, and must /always/ be
    represented by the "&lt;", "&gt;", "&quot;" and "&amp;" entities when
    they appear in the manual text.

  Comments are enclosed in "<!--" and "-->", and can span multiple lines.

  There is one small extension to the XML syntax, which is that some
  attributes can contain their own entities /and/ tags. These are used
  sparingly, and will be clearly documented when they arise.

  3.1. Character sets and encodings
  ---------------------------------

  XMLMan source files are always treated as being in UTF-8. To make it
  easier to work on different platforms, many standard HTML 5 entities are
  supported -- for example "&ndash;" for the en-dash in this sentence, or
  "&Aacute;" for a capital A with an acute accent (). By sticking to
  standard "ASCII-range" characters and using entities, it is possible to
  create files which can be safely edited on both RISC OS and other
  platforms.

  The encoding used for output files is specified when calling XMLMan from
  the command line. Characters which can be represented in the target
  encoding will be converted and written to the output, while those which
  can't will be replaced by a question mark -- a warning will be issued for
  each one. Some output modes handle the conversion differently, and this is
  documented in their specific sections of this manual.

  The encodings listed in Table 3.1. are supported.

  Encoding                              Parameter
  ---------------------------------------------------------------------------
  Acorn Latin 1                         AcornL1
  Acorn Latin 2                         AcornL2
  Unicode UTF-8                         UTF8
  7 Bit                                 7Bit

                  Table 3.1. Supported output encoding types

  3.2. Internal references
  ------------------------

  Internal references link from areas of the text to objects such as
  chapters, sections, tables and code blocks ("listings"). These enable
  items such as "see Chapter 2" or "as shown in Table 4" to be entered
  easily, along with hyperlinks where the output format allows for these.

  Reference IDs are specified using the id attribute within appropriate
  target tags, and can be any alphanumeric text. However, references map to
  object IDs in HTML output and since the IDs head, head-liner, body, body-
  liner, foot and foot-liner are used within the page structure, these are
  not available within a manual.

  3.3. External definitions
  -------------------------

  It is possible to supply externally-sourced content for a manual, in the
  form of short text definitions supplied with the -define parameter on the
  command line. The primary use case for this functionality is to support
  the embedding of build dates and version numbers into software manuals.

  In the manual document, these defines can be accessed using "<define>"
  tags.

    <p>The software was built on <define name="builddate" />.</p>

  3.4. The Manual
  ---------------

  The top level of an XMLMan document are the "<manual>" tags, which enclose
  the complete manual.

    <manual>
    
      <!-- The manual contents -->
    
    </manual>

  A manual can contain a number of tags, as follows.

    3.4.1. Title
    ------------

    The manual title is contained in "<title>" tags. This is the title used
    for the whole manual.

      <manual>
        <title>The XMLMan Manual</title>
      
        <!-- The manual contents -->
      
      </manual>

    A title is a single paragraph-like object containing text and markup.

4. HTML output
--------------

  The HTML output mode will generate a copy of the manual in HTML 5 format,
  across one or more files.

  4.1. Character encoding
  -----------------------

  The selected output encoding will control the way that the HTML output is
  generated. An attempt will be made to map all characters into the target
  encoding; if this fails, then an entity will be used instead. Named
  entities are used in preference, but if one isn't available, then a
  numeric entity (in the form "&#1234;") will be used instead.

  If output is in UTF-8 mode, it follows that the only characters to be
  output as entities will be the standard <, >, " and & as required by the
  HTML standard. If the use of entities is desired, this can be forced by
  selecting 7-Bit output mode: this will still output a file identified as
  being UTF-8 in order to achieve maximum compatibility, but will only use
  single-byte character encodings. All characters outside of this range will
  therefore be written out as entities.

5. Version History
------------------

  Here is a list of the versions of XMLMan, along with all of the changes
  made.

  5.1. Test Build
  ---------------

  Initial release for testing and feedback.

Updates and Contacting Me
-------------------------

  If you have any comments about XMLMan, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to XMLMan and more software for RISC OS computers can be found on
  my website at http://www.stevefryatt.org.uk/risc-os.

  Stephen Fryatt
  email: info@stevefryatt.org.uk
