docs/wiki/geda-style_guide.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 class="sectionedit1" id="style_guide">Style Guide</h1>
  14 <div class="level1">
  15 <div class="notewarning">This is definitely a work in progress.
  16 </div>
  17 <p>
  18 All documentation is eventually going to be made available as both <abbr title="HyperText Markup Language">HTML</abbr> and PDF.<br/>
  19
  20 The problem is to convert the gEDA wiki&#039;s Dokuwiki-pages (i.e., XHTML) into a format that can be converted into PDF.<br/>
  21
  22 The ideal path would be to use the pavuk application to mine the gEDA wiki, converting the XHTML wiki-pages into <abbr title="HyperText Markup Language">HTML</abbr> pages, and then use the HTMLDOC application to convert the <abbr title="HyperText Markup Language">HTML</abbr> pages to PDF.<br/>
  23
  24 </p>
  25
  26 </div>
  27 <!-- EDIT1 SECTION "Style Guide" [1-488] -->
  28 <h2 class="sectionedit2" id="downloading_installing_pavuk">Downloading/Installing pavuk</h2>
  29 <div class="level2">
  30
  31 <p>
  32 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.<br/>
  33
  34 pavuk is hosted on SourceForge at <a href="http://sourceforge.net/projects/pavuk" class="urlextern" title="http://sourceforge.net/projects/pavuk" rel="nofollow">http://sourceforge.net/projects/pavuk</a>. 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.<br/>
  35
  36 pavuk comes as an RPM, a tar-ball, and a compressed tar-ball. Don&#039;t install from the RPM, as this uses dated library dependencies and may not build on newer distributions.<br/>
  37
  38 pavuk has both a command-line interface and a <abbr title="Graphical User Interface">GUI</abbr> interface.
  39 </p>
  40
  41 </div>
  42 <!-- EDIT2 SECTION "Downloading/Installing pavuk" [489-1206] -->
  43 <h2 class="sectionedit3" id="downloading_installing_htmldoc">Downloading/Installing HTMLDOC</h2>
  44 <div class="level2">
  45
  46 <p>
  47 HTMLDOC converts <abbr title="HyperText Markup Language">HTML</abbr> files and web pages into indexed <abbr title="HyperText Markup Language">HTML</abbr>, PostScript, and PDF files suitable for on-line viewing and printing.<br/>
  48
  49 HTMLDOC is hosted at <a href="http://www.easysw.com/htmldoc/" class="urlextern" title="http://www.easysw.com/htmldoc/" rel="nofollow">http://www.easysw.com/htmldoc/</a>, 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).<br/>
  50
  51 HTMLDOC version htmldoc-1.8.26 is broken, it will not generate appropriate PDF documents.<br/>
  52
  53 Note one limitation of HTMLDOC. It is based on <abbr title="HyperText Markup Language">HTML</abbr> 3.o, not <abbr title="HyperText Markup Language">HTML</abbr> 4.01. Many <abbr title="HyperText Markup Language">HTML</abbr> 4.01 tags are not recognized by HTMLDOC.<br/>
  54
  55 HTMLDOC is both a <abbr title="Graphical User Interface">GUI</abbr> application and a command-line application. Use it as you feel most comfortable.
  56 </p>
  57
  58 </div>
  59 <!-- EDIT3 SECTION "Downloading/Installing HTMLDOC" [1207-2188] -->
  60 <h2 class="sectionedit4" id="for_both_existing_and_new_documents">For both existing and new documents</h2>
  61 <div class="level2">
  62
  63 <p>
  64 The following are meant to stimulate discussion on document style:
  65 </p>
  66 <ol>
  67 <li class="level1 node"><div class="li"> Consider that the document may be exported for inclusion in tool manuals as XHTML and/or PDF. Examples:</div>
  68 <ul>
  69 <li class="level2"><div class="li"> <a href="http://www.geda-project.org/wiki/?do=export_raw" class="urlextern" title="http://www.geda-project.org/wiki/?do=export_raw" rel="nofollow">http://www.geda-project.org/wiki/?do=export_raw</a> will generate the gEDA Project Wiki&#039;s start page as plain text.</div>
  70 </li>
  71 <li class="level2"><div class="li"> <a href="http://www.geda-project.org/wiki/?do=export_xhtml" class="urlextern" title="http://www.geda-project.org/wiki/?do=export_xhtml" rel="nofollow">http://www.geda-project.org/wiki/?do=export_xhtml</a> will generate the gEDA Project Wiki&#039;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.</div>
  72 </li>
  73 <li class="level2"><div class="li"> <a href="http://www.geda-project.org/wiki/?do=export_xhtmlbody" class="urlextern" title="http://www.geda-project.org/wiki/?do=export_xhtmlbody" rel="nofollow">http://www.geda-project.org/wiki/?do=export_xhtmlbody</a> will generate the gEDA Project Wiki&#039;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.</div>
  74 </li>
  75 <li class="level2"><div class="li"> The following sequence of commands will retreive a gEDA Project Wiki page (for a list of the gEDA Project Wiki&#039;s pages, use the Index button at the bottom of the page) from the “geda” namespace (when new wiki-pages are created, we <em class="u">explicitly</em> create them in the “geda” namespace) and convert that page into a PDF document:<br/>
  76 <pre class="code">% wget --convert-links -O {page-name}.wget %%&quot;http://www.geda-project.org/wiki/geda:{page-name}?do=export_html&quot;%%
  77 % sed -e &#039;s/\&amp;amp;/\&amp;/g&#039; {page-name}.wget &gt; {page-name}.sed
  78 % iconv -f utf-8 -t iso-8859-1 {page-name}.sed &gt; {page-name}.iconv
  79 % htmldoc {page-name}.iconv -t pdf14 --webpage --no-title --linkstyle underline --size letter --left 1.00in \\
  80   --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer . --nup 1 --tocheader .t. --tocfooter ..i \\
  81   --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 \\
  82   --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 \\
  83   --links --no-embedfonts --pagemode document --pagelayout single --firstpage p1 --pageeffect none \\
  84   --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password &quot;&quot;
  85   --user-password &quot;&quot; --browserwidth 680 -f {page-name}.pdf</pre>
  86
  87 <p>
  88  <br/>
  89 where <strong><code>{page-name}</code></strong> is the wiki&#039;s page name as seen in the upper-left corner of the wiki.
  90 </p>
  91 </div>
  92 </li>
  93 </ul>
  94 </li>
  95 </ol>
  96
  97 <p>
  98 For example, you would replace {page-name} above with the following for the related wiki-page:
  99 </p>
 100 <ul>
 101 <li class="level1"><div class="li"> start – The wiki&#039;s main page, at <a href="http://wiki.geda-project.org" class="urlextern" title="http://wiki.geda-project.org" rel="nofollow">http://wiki.geda-project.org</a>.</div>
 102 </li>
 103 <li class="level1"><div class="li"> geda:style_guide – This wiki-page, at <a href="http://www.geda-project.org/wiki/geda:style_guide" class="urlextern" title="http://www.geda-project.org/wiki/geda:style_guide" rel="nofollow">http://www.geda-project.org/wiki/geda:style_guide</a>.</div>
 104 </li>
 105 <li class="level1"><div class="li"> geda:faq – The wiki&#039;s <abbr title="Frequently Asked Questions">FAQ</abbr> page, at <a href="http://www.geda-project.org/wiki/geda:faq" class="urlextern" title="http://www.geda-project.org/wiki/geda:faq" rel="nofollow">http://www.geda-project.org/wiki/geda:faq</a></div>
 106 </li>
 107 </ul>
 108
 109 <p>
 110 A <a href="geda-sample_script.html" class="wikilink2" title="geda-sample_script.html">sample script</a> [<img src="images/smileys/fixme.gif" align="middle" alt="FIXME" />] to convert a single wiki-page into a PDF document.<br/>
 111
 112 A <a href="geda-sample_script.html" class="wikilink2" title="geda-sample_script.html">sample script</a> [<img src="images/smileys/fixme.gif" align="middle" alt="FIXME" />] to convert multiple wiki-pages into a single PDF document.
 113 </p>
 114
 115 <p>
 116 An example of the current (as of 08 May 2006) version of the Wiki, <a href="http://www.offramp.com/wiki/FC5_files/Wiki.pdf" class="urlextern" title="http://www.offramp.com/wiki/FC5_files/Wiki.pdf" rel="nofollow">converted to PDF</a>[<img src="images/smileys/fixme.gif" align="middle" alt="FIXME" />: broken link].
 117 </p>
 118
 119 </div>
 120 <!-- EDIT4 SECTION "For both existing and new documents" [2189-5272] -->
 121 <h2 class="sectionedit5" id="for_new_documents">For new documents:</h2>
 122 <div class="level2">
 123
 124 <p>
 125 The following are meant to stimulate discussion on document style:
 126 </p>
 127 <ol>
 128 <li class="level1"><div class="li"> 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.</div>
 129 </li>
 130 <li class="level1"><div class="li"> <strong>All</strong> 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.</div>
 131 </li>
 132 <li class="level1"><div class="li"> All documents are to be maintained in the “geda” <a href="https://www.dokuwiki.org/namespaces" class="urlextern" title="https://www.dokuwiki.org/namespaces" rel="nofollow">namespace</a>. 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 <a href="http://wiki.splitbrain.org/wiki:index" class="urlextern" title="http://wiki.splitbrain.org/wiki:index" rel="nofollow">Index</a> [<img src="images/smileys/fixme.gif" align="middle" alt="FIXME" />: broken link] for more details).</div>
 133 </li>
 134 </ol>
 135
 136 </div>
 137 <!-- EDIT5 SECTION "For new documents:" [5273-6397] -->
 138 <h2 class="sectionedit6" id="for_existing_documents">For existing documents:</h2>
 139 <div class="level2">
 140
 141 <p>
 142 The following are meant to stimulate discussion on document style:
 143 </p>
 144 <ol>
 145 <li class="level1"><div class="li"></div>
 146 </li>
 147 </ol>
 148
 149 </div>
 150 <!-- EDIT6 SECTION "For existing documents:" [6398-] --></body>
 151 </html>