Copyright © 2006 Robert Bienert
This material has been released under and is subject to the terms of the Common Documentation License, v.1.0, the terms of which are hereby incorporated by reference. Please obtain a copy of the License at http://www.opensource.apple.com/cdl/ and read it before using this material. Your use of this material signifies your agreement to the terms of the License.
Abstract
This document describes the inidoc program including the inidoc syntax.
Table of Contents
Abstract
The PHP program inidoc is contributed with LayManSys and is used internally for documentating configuration files in a so-called INI format; this file format is typically used for config files under MS Windows™ or by PHP web applications. inidoc uses special comments in the INI files and generates DocBook XML output.
php inidoc.php {file...}
inidoc needs at least one input file for generating the program output, which is sent to the standard output. That means you may want to pipe the output into a file. An advantage of this behaviour is that you can also use inidoc as a web service.
The programs output format is DocBook XML, where each INI file is documented within a <section>.
Normal text is put into <para> tags and the key-value pairs are described using a <glosslist>.
You can find a sample input and the generated output in the section Sample File.
inidoc uses the same INI file format as PHP does with its php.ini configuration file and recognized by the parse_ini_file function:
; as the first character of a new line and go till the end of this line.=, so note, that a keys name has not to contain an equal sign.Sections, written as [, are not supported and will lead to parsing errors.SectionName]
inidoc comments are normal INI file comments, that means, lines starting with a semi-colon as described above, but this semi-colon is followed immediately by an commercial at, @.
To make it more clear:
Example 1. Differences between normal INI file and inidoc comments.
; normale INI file comment, nothing special ;@ inidoc comment
An inidoc comment is ended by the first line without a inidoc comment; this can be a blank line, a key-value pair or even a normal INI comment:
Example 2.
;@ This lines ... ;@ ... belong all ... ;@ ... together ; ;@ ... while this is a new paragraph.
As you can see, using a blank comment may a good way telling inidoc to start a new paragraph.
inidoc comments directly before and after a key-value pair belong to this pair; the term directly means that there is no paragraph break as described above between the pair and its comment. See this example for a better explanation:
Example 3. inidoc comments for paragraphs and key-value pairs
;@ This is a inidoc comment, followed by a blank line. ;@ Here we start the next paragraph ;@ for documenting the following key-value pair: key=value ;@ <constant>value</constant> is of <type>value_type</type>. ;@ Only the four lines surrounding the pair document it. ; ;@ As you see in the paragraph above, we used some DocBook XML as markup.
inidoc does not escape special XML characters like < > " ' &, so if you want to have an arrow -> you have to write ->.
Although escaping special characters may not be very handy, it gives you the big advantage, using markup in your comments.
As inidoc produces DocBook XML output, you can use this markup language for documenting your INI files, too.
Let us use the example inidoc comments for paragraphs and key-value pairs and the Sample File to explain how inidoc works:
<para>.<glosslist>.
The keys name is used for the <glossterm>, while the information before and after as well as the key-value pair itself are put into the <glossdef> inside a <para>.
The key-value pair is documented as example in a <screen> environment, surrouned by the text directly before and after it.Using The inidoc Syntax we created this INI file (taken from the LayManSys definitions):
Example A.1. INI file
; $Id: layout.ini,v 1.2 2006/04/21 19:53:55 robertbienert Exp $ ; ; This is a sample layout.cfg file in INI format as expected by ; LayManSys if using a definition of type text/plain-ini. ; ; Copyright (C) 2006 Robert Bienert, project LayManSys ; http://laymansys.sourceforge.net/ ; ; As an addition, this file contains inidoc comments, which are ; described in the contributed inidoc package. ;@ The layout.ini file format is one of two formats for layout.cfg ;@ files. It is based on the popular INI file format, using certain ;@ key, which are described in this section. ;@ Keys for CSS files (currently only for screen presentation): style-screen=path/to/screen.css ;@ ... and for printing: style-printer=path/to/print.css ;@ NOTE that the paths are relative to the document root. LayManSys also ;@ expects the files to be Cascading Style Sheets, other types are not ;@ supported by this kind of layout.cfg. ;@ Navigation only in HTML format, the path is relative to the document ;@ root, too: nav=path/to/nav.html
Now, calling inidoc we get this result:
Example A.2. DocBook XML output
<?xml version="1.0"?>
<section id="def.layout.ini">
<title id="def.layout.ini.title">
<filename>def/layout.ini</filename>
</title>
<para> The layout.ini file format is one of two formats for layout.cfg
files. It is based on the popular INI file format, using certain
key, which are described in this section.
</para>
<glosslist>
<glossentry>
<glossterm>
<code>style-screen</code>
</glossterm>
<glossdef>
<para> Keys for CSS files (currently only for screen presentation):
<screen><![CDATA[style-screen=path/to/screen.css]]></screen></para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>
<code>style-printer</code>
</glossterm>
<glossdef>
<para> ... and for printing:
<screen><![CDATA[style-printer=path/to/print.css]]></screen> NOTE that the paths are relative to the document root. LayManSys also
expects the files to be Cascading Style Sheets, other types are not
supported by this kind of layout.cfg.
</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>
<code>nav</code>
</glossterm>
<glossdef>
<para> Navigation only in HTML format, the path is relative to the document
root, too:
<screen><![CDATA[nav=path/to/nav.html]]></screen></para>
</glossdef>
</glossentry>
</glosslist>
</section>
This example is displayed with intentation only to show the programs XML output tree. inidoc writes the output without any intentation to save space (white space).
The DocBook XML output might be rendered like this:
Example A.3. Generated HTML output
The layout.ini file format is one of two formats for layout.cfg files. It is based on the popular INI file format, using certain key, which are described in this section.
style-screen
Keys for CSS files (currently only for screen presentation):
style-screen=path/to/screen.css
style-printer
... and for printing:
style-printer=path/to/print.css
NOTE that the paths are relative to the document root. LayManSys also expects the files to be Cascading Style Sheets, other types are not supported by this kind of layout.cfg.
nav
Navigation only in HTML format, the path is relative to the document root, too:
nav=path/to/nav.html