source: branches/lib/HELP_SOURCE/help.readme

ARB documentation
-----------------

    Sources for ARB helpfiles are located in 'HELP_SOURCE/source'.

    They contain plain text which is converted into .xml and
    stored in 'HELP_SOURCE/Xml'.

    These .xml files are converted into
    - Hypertext (stored in 'lib/help_html') and
    - Arb helpfiles (stored in 'lib/help')

    The difference between the original helpfiles
    from 'HELP_SOURCE/source' and the resulting ones
    in 'lib/help' is the formatting.


    The ARB software displays the helpfiles located in 'lib/help'.
    When you press the 'BROWSE' button, it displays those in 'lib/help_html'.

    The latter is also made available at http://help.arb-home.de/arb.html
    (updates from trunk every 24h)


    When editing helpfiles from inside the ARB software, it depends
    on DEBUG mode, what happens:
    - with DEBUG mode enable this edits the files in 'HELP_SOURCE/source'
      (if they are available)
    - in userland it edits the files in 'HELP_SOURCE/source'. After editing the
      changes are packed into an archive (ready to be sent to arb developers).


ARB help "syntax"
-----------------

    # comment
    UP                  <target>                   # may occur multiple times
    SUB                 <target>                   # may occur multiple times

    TITLE               concise title

                        verbose subtitle

    OCCURRENCE          ARB_PROGRAM/Menu/Submenu/Buttonname

    # historical section types (each allowed to occur once):
    DESCRIPTION         <running text>
    NOTES               <running text>
    EXAMPLES            <running text>
    WARNINGS            <running text>
    BUGS                <running text>

    # custom section type (each 'name' allowed to occur once):
    SECTION             name

                        <running text>


  <running text>:
  - should contain empty lines (to separate paragraphs, ...).
    - uses indentation (first line defines for whole paragraph;
      same indentation results in same structure-level).
  - lists can be defined by
    - using digits as first character (numbered-lists).
    - using '-' or '*' as first character (bullet-lists).
    - has to be first char of a paragraph (or consecutive line).
    - may be of same indentation-level as superior structure-level.
    - no empty lines needed between consecutive list-entries.
    - may be nested.
  - paragraphs containing multiple consecutive space characters
    - will not reflow, i.e. they will be handled as "preformatted" text or
      ASCII art.
    - they will be displayed in monospaced font in html version.
    - their width is limited (currently defaults to 91 chars; depends on
      help window default width). See also 'PREFORMATTED' below.
  - may contain links to other documents/resources using 'LINK{<target>}'


  <target>:
  - another name.hlp file (=internal link)
  - name.ps and name.pdf file (=files delivered with arb)
  - URLs starting with http[s]://, ftp:// or file:// (=external link)
  - email addresses: name@domain.tl
  - ticket number: #NUM (=link to arb bug tracker)

  Control comments:
  - '# PREFORMATTED WIDTH <num>' forces the next block to be handled as "preformatted"
                                 and increases the allowed width to <num>.
                                 <num> may be DEFAULT to force a preformatted text block
                                 with default width.
  - '# PREFORMATTED RESET'       resets the allowed width to the default (see above).
  - '# PREFORMATTED 1'           defines the next block to be a preformatted text block
                                 with default width. Does auto-RESET after block.