Go to QuArK Web Site
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

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) 2022, GNU General Public License by The QuArK (Quake Army Knife) Community - https://quark.sourceforge.io/

 [ Prev - Top - Next ]