Style Guide

This is definitely a work in progress.

All documentation is eventually going to be made available as both HTML and PDF.
The problem is to convert the gEDA wiki's Dokuwiki-pages (i.e., XHTML) into a format that can be converted into PDF.
The ideal path would be to use the pavuk application to mine the gEDA wiki, converting the XHTML wiki-pages into HTML pages, and then use the HTMLDOC application to convert the HTML pages to PDF.

Downloading/Installing pavuk

pavuk is a function-testing, performance-measuring, site-mirroring, web spider that is widely portable and capable of using scenarios to process a wide range of web transactions, including ssl and forms.
pavuk is hosted on SourceForge at http://sourceforge.net/projects/pavuk. Simply check if your distribution already includes the latest version of pavuk (pavuk-0.9.34 used for the current wiki), and download/install if necessary.
pavuk comes as an RPM, a tar-ball, and a compressed tar-ball. Don't install from the RPM, as this uses dated library dependencies and may not build on newer distributions.
pavuk has both a command-line interface and a GUI interface.

Downloading/Installing HTMLDOC

HTMLDOC converts HTML files and web pages into indexed HTML, PostScript, and PDF files suitable for on-line viewing and printing.
HTMLDOC is hosted at http://www.easysw.com/htmldoc/, and may be downloaded/installed under the open-source license for non-commercial applications. Simply check if you distribution already includes HTMLDOC version htmldoc-1.8-27 or later, and install as appropriate. Note that RPM distributions are available, so that your normal package install/update utilities may already contain HTMLDOC (e.g., htmldoc-1.8.27 is in Fedora Core 4 extras repository and may be installed using yum).
HTMLDOC version htmldoc-1.8.26 is broken, it will not generate appropriate PDF documents.
Note one limitation of HTMLDOC. It is based on HTML 3.o, not HTML 4.01. Many HTML 4.01 tags are not recognized by HTMLDOC.
HTMLDOC is both a GUI application and a command-line application. Use it as you feel most comfortable.

For both existing and new documents

The following are meant to stimulate discussion on document style:

  1. Consider that the document may be exported for inclusion in tool manuals as XHTML and/or PDF. Examples:
    • http://www.geda-project.org/wiki/?do=export_raw will generate the gEDA Project Wiki's start page as plain text.
    • http://www.geda-project.org/wiki/?do=export_xhtml will generate the gEDA Project Wiki's start page as valid XHTML. Simply use your browser to “Save Page As…”, and name the file {filename}.html. Note that the URLs in this file are NOT relative to this file, but are as they would be found on the gEDA Project Wiki.
    • http://www.geda-project.org/wiki/?do=export_xhtmlbody will generate the gEDA Project Wiki's start page as valid rendered XHTML. Simply use your browser to “Save Page As…”, and name the file {filename}.html. Note that the URLs in this file are NOT relative to this file, but are as they would be found on the gEDA Project Wiki.
    • The following sequence of commands will retreive a gEDA Project Wiki page (for a list of the gEDA Project Wiki's pages, use the Index button at the bottom of the page) from the “geda” namespace (when new wiki-pages are created, we explicitly create them in the “geda” namespace) and convert that page into a PDF document:
      % wget --convert-links -O {page-name}.wget %%"http://www.geda-project.org/wiki/geda:{page-name}?do=export_html"%%
% sed -e 's/\&/\&/g' {page-name}.wget > {page-name}.sed
% iconv -f utf-8 -t iso-8859-1 {page-name}.sed > {page-name}.iconv
% htmldoc {page-name}.iconv -t pdf14 --webpage --no-title --linkstyle underline --size letter --left 1.00in \\
  --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer . --nup 1 --tocheader .t. --tocfooter ..i \\
  --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 \\
  --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 \\
  --links --no-embedfonts --pagemode document --pagelayout single --firstpage p1 --pageeffect none \\
  --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password ""
  --user-password "" --browserwidth 680 -f {page-name}.pdf


      where {page-name} is the wiki's page name as seen in the upper-left corner of the wiki.

For example, you would replace {page-name} above with the following for the related wiki-page:

A sample script [FIXME] to convert a single wiki-page into a PDF document.
A sample script [FIXME] to convert multiple wiki-pages into a single PDF document.

An example of the current (as of 08 May 2006) version of the Wiki, converted to PDF[FIXME: broken link].

For new documents:

The following are meant to stimulate discussion on document style:

  1. You must “own” all content in the document. If you do not “own” the content, you must get explicit permission from the “owner” to copy the content to the gEDA Project Wiki (see below). Documents on the gEDA Project Wiki should be stand-alone, in the event the source document web-site disappears.
  2. All document contents are to be hosted on the gEDA Project Wiki. Images and other media files are to be uploaded to the wiki, and linked to. Do NOT link to external sites unless absolutely necessary.
  3. All documents are to be maintained in the “geda” namespace. If your document would take advantage of a separate namespace, ask Ales if “geda:sub-namespace” is acceptable. This would be appropriate for very large documents with multiple chapters and lots of images. Such a namespace structure would allow the document to be “broken” into chapters for easier navigation by the user (see Index [FIXME: broken link] for more details).

For existing documents:

The following are meant to stimulate discussion on document style: