| Documenting QuArK Updated 05 Apr 2018 | Upper levels: - QuArK Information Base - 3. Advanced customization

3.9. Documenting QuArK | [ Prev - Up - Next ]

Index

- - The Information Base (05 Apr 2018)
- - Information Base Syntax (05 Apr 2018)

The Information Base | Armin Rigo - 05 Apr 2018 | [ Top ]

The Information Base is the source of information that you're just reading. It is written as a set of organized text files whose format is described below. The tool that translates these files and directories into a set of HTML files is the Python script `build.py` . The directories correspond to the classification in the final HTML files. Each directory must contain a file `index.txt` which gives the overall description of the category; it can also contain any number of other `.txt` files, which will be grouped into a single HTML. Each such text file correspond to a "question/answer" or item of discussion.

Information Base Syntax | Armin Rigo / tiglari / Decker - 05 Apr 2018 | [ Top ]

All `.txt` files in the infobase are formatted as follow: First, a list of keyword-value pairs, ended with a blank line, and followed by the text itself. For example:
    title: This is the title of what this file contains.
    author: Your Name
    subdir: list subdirectories
    subdir: can be done on several lines
    desc: list files
    desc: without ".txt" extension

    The text follows the blank line.
The most common keywords are given in this example. Notice that `subdir` and `desc` only make sense in the file `index.txt` , while `author` is only used in the opposite case. Other keywords might be parsed in the future. Also note that all file names should be lowercase. The text itself is formatted paragraph-by-paragraph, with at least one blank line between paragraphs (a single end-of-line is not considered as separating two paragraphs). Do not use <P> and </P> tags, as these will be automatically applied. If `build.py` finds any, it will complain. You are able to use basic HTML tags within the text (except the previously mentioned), but you must ensure that tags are not split between 2 or more lines, as `build.py` then can't find the end of the tag. For instance this is illegal:
      <table border=1
      cellpadding=0 cellspacing=0>
Whereas this is the correct way to do it:
      <table border=1 cellpadding=0 cellspacing=0>
Some special tags, that `build.py` checks for: <code> text to appear in code-format </code> To format code examples, put it within these tags. Notice that the < (less than) character must be written with the HTML-code `&lt;` else `build.py` might complain about not finding the ending > (greater than) character. <ref> link </ref> <ref> link \ link_text </ref> The link is supposed to be a path & filename to another file of the InfoBase directory, relative to the root. If you want something other than the section title to appear in the text, separate it from the filename with '\'. Notice that the ending </ref>-tag must be on the same line as the start-tag! <img arg=value > image </img> You can have additional arguments in the <img>-tag, just as in normal HTML. The image must point to a `.GIF` , `.JPG` or `.PNG` image-file within the same directory of the `.txt` file. Notice that the ending </img>-tag must be on the same line as the start-tag! You can also use the <pic>-tag for this; they are equivalent. <zip> file </zip> The file is taken as the name of an `archive'. Archives are treated in a special way due to the disinclination of web-hosting to allow direct downloading of .zip files from ordinary web-pages. Archives are expected to appear in the subfolder `zips` . How they are processed depends on whether `build.py` is launched with the command-line argument `-local` or not. If it is, then the archive file is copied into the a subfolder `zips` in `output` , and a suitable link generated. If it isn't (the default), then no copying happens, and the link is prefixed by the value of the string `ZIPLOC` specified at the top of `format.txt` . The archives are then to be uploaded to the appropriate server independently of the operations of this script (but they should all be sitting in the `zips` folder). Notice that the ending </zip>-tag must be on the same line as the start-tag! <g> any word(s) to glossary </g> To make a, somewhat useful glossary, you can use these tags to indicate that the word (actually only the first letter of the word, for the moment) links to the glossary. Notice that the ending </g>-tag must be on the same line as the start-tag! <act> 1st menuaction | 2nd menuaction | etc. </act> To indicate a series of menu-actions, the user should perform to activate or execute something, you can use these tags. Notice that the ending </act>-tag must be on the same line as the start-tag! <link link-name > link-text </link> Creates a link to an external website. The links are listed in `links.py', with link-name being the key to the dictionary, and link-text is the link's text to display. Notice that the ending </link>-tag must be on the same line as the start-tag! List of examples:
This text... | ...will result in this
--- | ---
See <ref> adv/doc/infobase-format </ref> for more information. | See 'Information Base Syntax' for more information.
See <ref> adv/doc/infobase-format \ format stuff </ref> for more information. | See format stuff for more information.
To display in fixed font, which <TT>isn't code but text</TT>, you can use the TT-tags. | To display in fixed font, which `isn't code but text` , you can use the TT-tags.
See <ref> adv/doc/infobase-format </ref> for more information. | build.py will complain not finding ending tag.
<code> for i in range(0,9): print i &lt; 5, </code> |
    for i in range(0,9):
        print i < 5,
<img> quark.gif </img> |
<img align=right border=2> quark.gif </img> |
This is a link to the <g>QuArK</g> glossary. | This is a link to the QuArK glossary.
This is a link to <link forums>our forums</link>. | This is a link to our forums.
To set the texture-flags for a brush, mark that brush in the 2D-view and <act> RMB|Texture flags | Flags... </act>. | To set the texture-flags for a brush, mark that brush in the 2D-view and 'RMB -> Texture flags -> Flags...'.

Copyright (c) 2021, GNU General Public License by The QuArK (Quake Army Knife) Community - http://quark.sourceforge.net/ | [ Prev - Top - Next ]