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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
   4  lang="en" dir="ltr">
   5 <head>
   6   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   7   <title>geda:style_guide</title>
   8 <meta name="generator" content="DokuWiki Release rc2007-05-24" />
   9 <meta name="robots" content="index,follow" />
  10 <meta name="date" content="2007-05-24T22:27:25-0400" />
  11 <meta name="keywords" content="geda,style_guide" />
  12 <link rel="search" type="application/opensearchdescription+xml" href="http://geda.seul.org/wiki/lib/exe/opensearch.php" title="geda Wiki" />
  13 <link rel="start" href="http://geda.seul.org/wiki/" />
  14 <link rel="contents" href="http://geda.seul.org/wiki/geda:style_guide?do=index" title="Index" />
  15 <link rel="alternate" type="application/rss+xml" title="Recent Changes" href="http://geda.seul.org/wiki/feed.php" />
  16 <link rel="alternate" type="application/rss+xml" title="Current Namespace" href="http://geda.seul.org/wiki/feed.php?mode=list&ns=geda" />
  17 <link rel="alternate" type="text/html" title="Plain HTML" href="http://geda.seul.org/wiki/_export/xhtml/geda:style_guide" />
  18 <link rel="alternate" type="text/plain" title="Wiki Markup" href="http://geda.seul.org/wiki/_export/raw/geda:style_guide" />
  19 <link rel="stylesheet" media="all" type="text/css" href="lib/exe/css" />
  20 <link rel="stylesheet" media="screen" type="text/css" href="lib/exe/001css" />
  21 <link rel="stylesheet" media="print" type="text/css" href="lib/exe/002css" />
  22 </head>
  23 <body>
  24 <div class="dokuwiki export">
  25 <div class="toc">
  26 <div class="tocheader toctoggle" id="toc__header">Table of Contents</div>
  27 <div id="toc__inside">
  28
  29 <ul class="toc">
  30 <li class="level1"><div class="li"><span class="li"><a href="#style_guide" class="toc">Style Guide</a></span></div>
  31 <ul class="toc">
  32 <li class="level2"><div class="li"><span class="li"><a href="#downloading_installing_pavuk" class="toc">Downloading/Installing pavuk</a></span></div></li>
  33 <li class="level2"><div class="li"><span class="li"><a href="#downloading_installing_htmldoc" class="toc">Downloading/Installing HTMLDOC</a></span></div></li>
  34 <li class="level2"><div class="li"><span class="li"><a href="#for_both_existing_and_new_documents" class="toc">For both existing and new documents</a></span></div></li>
  35 <li class="level2"><div class="li"><span class="li"><a href="#for_new_documents" class="toc">For new documents:</a></span></div></li>
  36 <li class="level2"><div class="li"><span class="li"><a href="#for_existing_documents" class="toc">For existing documents:</a></span></div></li></ul>
  37 </li></ul>
  38 </div>
  39 </div>
  40
  41
  42
  43 <h1><a name="style_guide" id="style_guide">Style Guide</a></h1>
  44 <div class="level1">
  45
  46 <p>
  47 <span class="hilited">This is definitely a work in progress.</span><br/>
  48  All documentation is eventually going to be made available as both <acronym title="HyperText Markup Language">HTML</acronym> and <acronym title="Portable Document Format">PDF</acronym>.<br/>
  49  The problem is to convert the gEDA wiki’s Dokuwiki-pages (i.e., <acronym title="Extensible HyperText Markup Language">XHTML</acronym>) into a format that can be converted into <acronym title="Portable Document Format">PDF</acronym>.<br/>
  50  The ideal path would be to use the pavuk application to mine the gEDA wiki, converting the <acronym title="Extensible HyperText Markup Language">XHTML</acronym> wiki-pages into <acronym title="HyperText Markup Language">HTML</acronym> pages, and then use the HTMLDOC application to convert the <acronym title="HyperText Markup Language">HTML</acronym> pages to <acronym title="Portable Document Format">PDF</acronym>.<br/>
  51
  52 </p>
  53
  54 </div>
  55 <!-- SECTION "Style Guide" [1-472] -->
  56 <h2><a name="downloading_installing_pavuk" id="downloading_installing_pavuk">Downloading/Installing pavuk</a></h2>
  57 <div class="level2">
  58
  59 <p>
  60 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/>
  61  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/>
  62  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.<br/>
  63  pavuk has both a command-line interface and a <acronym title="Graphical User Interface">GUI</acronym> interface.
  64 </p>
  65
  66 </div>
  67 <!-- SECTION "Downloading/Installing pavuk" [473-1190] -->
  68 <h2><a name="downloading_installing_htmldoc" id="downloading_installing_htmldoc">Downloading/Installing HTMLDOC</a></h2>
  69 <div class="level2">
  70
  71 <p>
  72 HTMLDOC converts <acronym title="HyperText Markup Language">HTML</acronym> files and web pages into indexed <acronym title="HyperText Markup Language">HTML</acronym>, PostScript, and <acronym title="Portable Document Format">PDF</acronym> files suitable for on-line viewing and printing.<br/>
  73  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/>
  74  HTMLDOC version htmldoc-1.8.26 is broken, it will not generate appropriate <acronym title="Portable Document Format">PDF</acronym> documents.<br/>
  75  Note one limitation of HTMLDOC. It is based on <acronym title="HyperText Markup Language">HTML</acronym> 3.o, not <acronym title="HyperText Markup Language">HTML</acronym> 4.01. Many <acronym title="HyperText Markup Language">HTML</acronym> 4.01 tags are not recognized by HTMLDOC.<br/>
  76  HTMLDOC is both a <acronym title="Graphical User Interface">GUI</acronym> application and a command-line application. Use it as you feel most comfortable.
  77 </p>
  78
  79 </div>
  80 <!-- SECTION "Downloading/Installing HTMLDOC" [1191-2172] -->
  81 <h2><a name="for_both_existing_and_new_documents" id="for_both_existing_and_new_documents">For both existing and new documents</a></h2>
  82 <div class="level2">
  83
  84 <p>
  85 The following are meant to stimulate discussion on document style:
  86 </p>
  87 <ol>
  88 <li class="level1"><div class="li"> Consider that the document will be exported for inclusion on the “gEDA Tools Suite CD-ROM” as <acronym title="Extensible HyperText Markup Language">XHTML</acronym> and/or <acronym title="Portable Document Format">PDF</acronym>. Examples:</div>
  89 <ul>
  90 <li class="level2"><div class="li"> <a href="http://geda.seul.org/wiki/?do=export_raw" class="urlextern" title="http://geda.seul.org/wiki/?do=export_raw"  rel="nofollow">http://geda.seul.org/wiki/?do=export_raw</a> will generate the gEDA Project Wiki’s start page as plain text. Simply use your browser to copy to a text file and include on the CD-ROM image.</div>
  91 </li>
  92 <li class="level2"><div class="li"> <a href="http://geda.seul.org/wiki/?do=export_xhtml" class="urlextern" title="http://geda.seul.org/wiki/?do=export_xhtml"  rel="nofollow">http://geda.seul.org/wiki/?do=export_xhtml</a> will generate the gEDA Project Wiki’s start page as valid <acronym title="Extensible HyperText Markup Language">XHTML</acronym>. Simply use your browser to “Save Page As&hellip;”, 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>
  93 </li>
  94 <li class="level2"><div class="li"> <a href="http://geda.seul.org/wiki/?do=export_xhtmlbody" class="urlextern" title="http://geda.seul.org/wiki/?do=export_xhtmlbody"  rel="nofollow">http://geda.seul.org/wiki/?do=export_xhtmlbody</a> will generate the gEDA Project Wiki’s start page as valid rendered <acronym title="Extensible HyperText Markup Language">XHTML</acronym>. Simply use your browser to “Save Page As&hellip;”, 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>
  95 </li>
  96 <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’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 <acronym title="Portable Document Format">PDF</acronym> document:<br/>
  97  <pre STYLE="background : Lightgreen;margin-left : 2em"><font size="+0">% wget --convert-links -O {page-name}.wget &quot;http://geda.seul.org/wiki/geda:{page-name}?do=export_html&quot;
  98 % sed -e &#039;s/\&amp;amp;/\&amp;/g&#039; {page-name}.wget &gt; {page-name}.sed
  99 % iconv -f utf-8 -t iso-8859-1 {page-name}.sed &gt; {page-name}.iconv
 100 % htmldoc {page-name}.iconv -t pdf14 --webpage --no-title --linkstyle underline --size letter --left 1.00in \\
 101   --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer . --nup 1 --tocheader .t. --tocfooter ..i \\
 102   --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 11.0 --fontspacing 1.2 \\
 103   --headingfont Helvetica --bodyfont Times --headfootsize 11.0 --headfootfont Helvetica --charset iso-8859-1 \\
 104   --links --no-embedfonts --pagemode document --pagelayout single --firstpage p1 --pageeffect none \\
 105   --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password &quot;&quot;
 106   --user-password &quot;&quot; --browserwidth 680 -f {page-name}.pdf</font></pre> <br/>
 107  where <strong><code>{page-name}</code></strong> is the wiki’s page name as seen in the upper-left corner of the wiki.</div>
 108 </li>
 109 </ul>
 110 </li>
 111 </ol>
 112
 113 <p>
 114  For example, you would replace {page-name} above with the following for the related wiki-page:
 115 </p>
 116 <ul>
 117 <li class="level1"><div class="li"> start &ndash; The wiki’s main page, at <a href="http://geda.seul.org/wiki/" class="urlextern" title="http://geda.seul.org/wiki/"  rel="nofollow">http://geda.seul.org/wiki/</a>.</div>
 118 </li>
 119 <li class="level1"><div class="li"> geda:style_guide &ndash; This wiki-page, at <a href="http://geda.seul.org/wiki/geda:style_guide" class="urlextern" title="http://geda.seul.org/wiki/geda:style_guide"  rel="nofollow">http://geda.seul.org/wiki/geda:style_guide</a>.</div>
 120 </li>
 121 <li class="level1"><div class="li"> geda:faq &ndash; The wiki’s <acronym title="Frequently Asked Questions">FAQ</acronym> page, at <a href="http://geda.seul.org/wiki/geda:faq" class="urlextern" title="http://geda.seul.org/wiki/geda:faq"  rel="nofollow">http://geda.seul.org/wiki/geda:faq</a></div>
 122 </li>
 123 </ul>
 124
 125 <p>
 126  A <span class="hilited">sample script</span> to convert a single wiki-page into a <acronym title="Portable Document Format">PDF</acronym> document.<br/>
 127  A <span class="hilited">sample script</span> to convert multiple wiki-pages into a single <acronym title="Portable Document Format">PDF</acronym> document.
 128 </p>
 129
 130 <p>
 131 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>.
 132 </p>
 133
 134 </div>
 135 <!-- SECTION "For both existing and new documents" [2173-5272] -->
 136 <h2><a name="for_new_documents" id="for_new_documents">For new documents:</a></h2>
 137 <div class="level2">
 138
 139 <p>
 140 The following are meant to stimulate discussion on document style:
 141 </p>
 142 <ol>
 143 <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>
 144 </li>
 145 <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>
 146 </li>
 147 <li class="level1"><div class="li"> All documents are to be maintained in the “geda” <a href="http://wiki.splitbrain.org/wiki:namespaces" class="urlextern" title="http://wiki.splitbrain.org/wiki: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> for more details).</div>
 148 </li>
 149 </ol>
 150
 151 </div>
 152 <!-- SECTION "For new documents:" [5273-6383] -->
 153 <h2><a name="for_existing_documents" id="for_existing_documents">For existing documents:</a></h2>
 154 <div class="level2">
 155
 156 <p>
 157 The following are meant to stimulate discussion on document style:
 158 </p>
 159 <ol>
 160 <li class="level1"><div class="li"> </div>
 161 </li>
 162 </ol>
 163
 164 </div>
 165 <!-- SECTION "For existing documents:" [6384-] --></div>
 166 </body>
 167 </html>