<!doctype html public '-//W3C//DTD HTML 4.01//EN'>
<!-- Editors & translators, please, edit Overview.en.tmpl, not .html -->
<html lang=en>
 <head profile="http://microformats.org/profile/hcard">
  <title>Installation hints for the CSS3 module postprocessor</title>
  <!-- include head.inc -->
  <link rel=up title="CSS" href="../">
  <!-- include translations1 -->
 <body>
  <!-- include translations2 -->

  <h1><em>CSS3 module postprocessor</em>
   installation hints</h1>

  <div class=section id=intro>
   <p>The <a href="../../Group/css3-src/bin/postprocess">CSS3 module
   postprocessor</a> [member-only link] was not made with portability
   in mind, nor has it been checked very carefully for security
   issues, but if anybody wants to try and install it on another
   server, here are some hints.
   <ul>
    <li><a href="#prerequisites">Prerequisites</a>
    <li><a href="#configuration">Configuration</a>
    <li><a href="#interface">Interface</a>
   </ul>
  </div>

  <div class=section id=prerequisites>
   <h2>Prerequisites</h2>

   <p>The postprocessor is a CGI script written in bash that calls
   several other programs, some in C, some in sed and some in
   bash. The following software is required:

   <ul>
    <li>A Web server capable of executing CGI scripts.

    <li>bash, sed, tr, head, fgrep &ndash; the standard Unix
    utilities. It assumes the GNU version of sed, i.e., a version that
    accepts the <code>-r</code> option. It might work with BSD (or Mac
    OS X) sed as well, by replacing <code>-r</code> with
    <code>-E</code>, but that has not been tested very well.

    <li>wget &ndash; wget retrieves a document given a URL; it is
    available for many platforms.

    <li><a href="process.cgi">process.cgi</a> &ndash; the main CGI
    script.

    <li><a href="parseform.c">parseform.c</a> &ndash; a program to
    parse CGI parameters (from either GET or POST requests) and store
    their values in individual files. To compile: <code>cc -o
    parseform parseform.c</code>

    <li><a href="/Status#HTML-XML-utils">HTML-XML-utils</a> (also
    available as binary package in Debian) &ndash; a
    collection of programs in C for making cross-references,
    bibliographies, tables of contents, etc. Compilation instructions
    are included (it uses GNU autoconf).

    <li><a href="special-include">special-include</a> &ndash; a script
    that replaces comments of the form <code>&lt;!-- keyword
    --></code> by the contents of some file.

    <li><a href="quotestoclasses.l">quotestoclasses.l</a> &ndash;
    Flex program to replace <code>'foo'</code> and <code>''foo''</code>
    with mark-up. Only necessary for CSS modules, where 'foo' stands
    for a CSS property name and ''foo'' for a piece of CSS code.

    <li><a href="propdefdbtotable">propdeftotable</a> and <a
    href="propdeftodb">tabtodb</a> &ndash; two scripts that
    look for certain kinds of tables that define CSS properties and
    make a table summarizing all such properties.
   </ul>
  </div>

  <div class=section id=configuration>
   <h2>Configuration</h2>

   <p>The script looks for programs to execute and files to insert in
   certain places that must be set at the top of the script:

   <dl>
    <dt><code>bibfile</code> <dd>The name of a file in (restricted)
    refer format that contains bibliographic data. See refer(1) and
    the <a href="/Tools/HTML-XML-utils/man1/hxmkbib.html"> manual of
    hxmkbib</a> for the format. Or see this <a
    href="biblio.ref">example.</a>

    <dt><code>biblioinc</code> <dd>The name of a file with a template
    for the bibliography. See the <a
    href="/Tools/HTML-XML-utils/man1/hxmkbib.html"> manual of
    hxmkbib</a> for the format. or see this <a
    href="biblio.inc">example.</a>

    <dt><code>copyright</code> <dd>The name of a file containing a
    copyright statement. This will be inserted where the input
    document contains the comment <code>&lt;!-- copyright --></code>.

    <dt><code>statusdir</code> <dd>If the input document contains
    <code>&lt;!-- status --></code> or <code>&lt;!-- conformance
    --></code>, a file will be inserted with an appropriate status or
    conformance message for the document's status and working
    group (see the <code>group</code> parameter below). Those files
    are searched for in this directory.

    <dt><code>PATH</code> <dd>May need to be adapted so that the
    script can find all of the programs or scripts that it needs.
   </dl>
  </div>

  <div class=section id=interface>
   <h2>Interface</h2>

   <p>The API of the postprocessor is built on top of CGI. It accepts
   both GET and POST requests, with the following parameters:

   <dl>
    <dt><code>output</code> <dd>Determines what the CGI script
    returns. The value must be <code>err</code>,
    <code>html</code> or <code>auto</code>. The first returns the list
    of errors that were discovered while processing the input, or the
    string <code>No errors</code>. The second returns the generated
    output itself. And <code>auto</code> returns the generated output
    if there were no errors, and an HTTP error otherwise.

    <dt><code>method</code> <dd>Determines how the input is passed to
    the script. The value must be either <code>file</code>,
    <code>text</code> or <code>url</code>. The first indicates that
    the input is passed in the <code>file</code> parameter, the second
    that it is passed in the <code>text</code> parameter and the last
    that the input must be retrieved by the CGI script itself from the
    URL in the <code>url</code> parameter.

    <dt><code>group</code> <dd>Certain parts of a document may depend
    on which working group is the author, e.g., the status section or
    whether or not CSS code is marked-up specially. The name passed
    here is used to find files to include.

    <dt><code>login</code> <dd>(Only if <code>method=url</code>.) If
    the script must retrieve the input from a password-protected URL,
    this parameter gives the login name.

    <dt><code>password</code> <dd>(Only if <code>method=url</code>.) 
    If the script must retrieve the input from a password-protected
    URL, this parameter gives the password.

    <dt><code>date</code> <dd>Anywhere where a date should be inserted
    in a document, this date is used. It must be of the form
    YYYYMMDD. If omitted or empty, the current date is used.

    <dt><code>ids</code> <dd>Indicates whether the script should
    generate ID attributes on all P and LI elements in the
    document. The value must be <code>on</code>. Anything else means
    no such IDs are generated.

    <dt><code>file</code> <dd>(Only if <code>method=file</code>.) 
    Contains the input document. By convention
    <code>method=file</code> indicates that the form used file upload,
    while <code>method=text</code> means the form used a text field.

    <dt><code>text</code> <dd>(Only if <code>method=text</code>.) 
    Contains the input document.

    <dt><code>url</code> <dd>(Only if <code>method=url</code>.) 
    Contains the URL where the script should download the input
    document.

    <dt><code>status</code> <dd>Must be one of WD, CR, PR, REC, PER,
    NOTE or ED. If omitted or empty, the script looks for a status
    code in the “this version” URL in the document itsef. If it finds
    none, it assumes ED. (Note: if the status parameter conflicts with
    the URL, the URL is <em>not</em> corrected.)

    <dt><code>omitdchtml</code> <dd>Normally, the script tries to add
    META and LINK elements according to <a href="" >DC-HTML</a> to aid
    reference managers to automatically extract bibliographic
    information. Those META and LINK elements are not generated if
    this is set to <code>on</code>. Also, if the document already has
    DC-HTML mark-up, setting this to <code>on</code> avoids that some
    of it gets overwritten.
   </dl>

   <p>The response headers contain a nonstandard line

   <pre>X-W3C-Postprocessor-Errors: 0</pre>

   <p>where &ldquo;0&rdquo; is replaced by the actual number of errors
   found while processing the input. This allows to get in a single
   request both the generated HTML and the number of errors. The line
   is also returned if the request is a HEAD.
  </div>

  <!-- include feedback -->

  <!-- include banner -->

  <div class=section id=endmatter>
   <!-- include address -->

   <p>Last updated
    <!-- include date -->
  </div>

  <!-- include translations4 -->

<!-- Keep this comment at the end of the file
Local variables:
mode: html
sgml-indent-step:1
sgml-indent-data:t
sgml-basic-offset:1
End:
-->
