25 Sep 2001

Added
README.txt
hamlib-doc.dsl		-- Forgot these on SGML commit...


git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@666 7ae35d74-ebe9-4afe-98af-79ac388436b8

doc/sgml/README.txt

@@ -0,0 +1,88 @@
+README.txt - the companion answer file for the Hamlib SGML source 
+distribution.  Copyright (C) 2001 by Nathan Bargmann n0nb@arrl.net
+under the terms of the GNU General Public License version 2.0.
+
+Notes for hamlib-doc for version 1.1.0 (ALPHA)
+
+GENERAL:
+
+      This is the initial release of hamlib-doc, version 0.1.1.  Covered
+      topics include licensing of Hamlib, where and how to get the latest
+      stable and CVS versions, introductory material on building, and
+      API reference.
+      
+      Generated formats are HTML, PS and PDF at this time.
+
+BUILDING:
+
+      The source files are SGML marked up text that validates against the
+      Docbook 3.1 DTD.  Build environment is Debian GNU/Linux Woody a.ka. 
+      3.0 and required tools are Jade and nsgmls and the Cynus stylesheets.
+      If you plan to use a Debian system I strongly recommend doing it on
+      a Woody box as I had a number of issues with the output generated
+      by the tools in the Potato release.
+      
+      The proper DTD is required.  Installing the sgml-tools task from 
+      dselect or apt-get will get all the DTDs and catalogs you'd ever 
+      need installed.
+      
+  PDF:
+      The PDF is built with the Cygnus db2pdf script, however, there is an
+      included Docbook stylesheet, hamlib-doc.dsl.  Invoke the db2pdf script
+      in the same directory as the .sgml files with -d option:
+
+	  db2pdf -d hamlib-doc hamlib-doc.sgml
+	  
+      and you'll wind up with a nice .pdf file.
+
+  HTML:
+      To generate the HTML files I use a similar script called db2html that
+      is invoked as above.  The script will create and place the HTML and
+      other files in a subdirectory.
+
+  PS:
+      Same as above except the script in Woody won't accept the -d option for
+      a custom DSSSL file.
+
+  SGML:
+      Any editor may be used to edit the SGML source files.  After editing,
+      the SGML needs to be validated to ensure proper element placement and 
+      typos in the SGML structure.  An excellent tool to do this is nsgmls.  
+      You can validate the files from the directory where the files are 
+      stored:
+
+	nsgmls -sv hamlib.sgml	    # validates the sgml
+
+      If there are no validation issues, nsgmls will return a prompt with
+      no output except its version.
+
+BUGS:
+
+      Bugs?  What bugs?  All bugs were taken out and shot!
+
+      I wish...
+
+      To enable links in the reference section I used brute force and
+      marked up hyperlinks into the text flow.  The .pdf has the hyperlinks
+      in the text, but they're not annotated in any special way except
+      beginning with http:.
+
+      Probably more as I'm too tired to look for them...
+      
+TODO:
+
+      Sections covering Hamlib usage in a program, writing a backend,
+      and Hamlib internals.
+
+      Document top-level structures used by the API.
+
+      Sync with CVS version.
+      
+MISC:
+
+      I appreciate all feedback.  Assistance won't be ignored either!
+      Write me at n0nb@arrl.net
+
+      73, de Nate >>
+
+      

doc/sgml/hamlib-doc.dsl

@@ -0,0 +1,155 @@
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY % html "IGNORE">
+<![%html;[
+<!ENTITY % print "IGNORE">
+<!ENTITY docbook.dsl SYSTEM "/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl" CDATA dsssl>
+]]>
+<!ENTITY % print "INCLUDE">
+<![%print;[
+<!ENTITY docbook.dsl SYSTEM "/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl" CDATA dsssl>
+]]>
+]>
+
+<!-- Cygnus customizations by Mark Galassi -->
+<!-- Shamelessly appropriated for Hamlib-doc by Nate Bargmann
+     n0nb@arrl.net.  Original file is cygnus-both.dsl from the
+     Cygnus tools collection.  This seemed easier than writing
+     a new .dsl and coordinating with this file...
+-->
+
+
+<style-sheet>
+
+
+<style-specification id="print" use="docbook">
+<style-specification-body> 
+
+;; ====================
+;; customize the print stylesheet
+;; ====================
+
+;; make funcsynopsis look pretty
+(define %funcsynopsis-decoration%
+  ;; Decorate elements of a FuncSynopsis?
+  #t)
+
+;; use graphics in admonitions, and have their path be "."
+;; NO: we are not yet ready to use gifs in TeX and so forth
+(define %admon-graphics-path%
+  "./")
+(define %admon-graphics%
+  #f)
+
+;; this is necessary because right now jadetex does not understand
+;; symbolic entities, whereas things work well with numeric entities.
+(declare-characteristic preserve-sdata?
+          "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
+          #f)
+(define %two-side% #t)
+
+(define %section-autolabel% 
+  ;; Are sections enumerated?
+  #t)
+;; (define %title-font-family% 
+;;   ;; The font family used in titles
+;;   "Ariel")
+(define %visual-acuity%
+  ;; General measure of document text size
+  ;; "presbyopic"
+  ;; "large-type"
+  "presbyopic")
+
+(define %generate-part-toc% #t)
+
+;; (define %block-start-indent% 10pt)
+
+(define %graphic-default-extension% "eps")
+
+;; added by Nate Bargmann to start RefEntry on a new page.
+;; REFERENCE RefEntries and FuncSynopses
+
+(define %refentry-new-page% 
+  ;; REFENTRY refentry-new-page
+  ;; PURP 'RefEntry' starts on new page?
+  ;; DESC
+  ;; If true, each 'RefEntry' begins on a new page.
+  ;; /DESC
+  ;; AUTHOR N/A
+  ;; /REFENTRY
+  #t)
+
+(element (varlistentry term)
+  (make paragraph
+    space-before: (if (first-sibling?)
+		      %block-sep%
+                      0pt)
+    keep-with-next?: #t
+    first-line-start-indent: 4em
+    start-indent: 0pt
+    (process-children)))
+
+
+</style-specification-body>
+</style-specification>
+
+<!--
+;; ====================
+;; customize the html stylesheet
+;; ====================
+-->
+<style-specification id="html" use="docbook">
+<style-specification-body> 
+
+;; this is necessary because right now jadetex does not understand
+;; symbolic entities, whereas things work well with numeric entities.
+(declare-characteristic preserve-sdata?
+          "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
+          #f)
+
+;; put the legal notice in a separate file
+(define %generate-legalnotice-link%
+  #t)
+
+;; use graphics in admonitions, and have their path be "stylesheet-images"
+;; NO: they do not yet look very good
+(define %admon-graphics-path%
+  "./stylesheet-images/")
+(define %admon-graphics%
+  #f)
+
+;; make funcsynopsis look pretty
+(define %funcsynopsis-decoration%
+  ;; Decorate elements of a FuncSynopsis?
+  #t)
+
+(define %html-ext% ".html")
+(define %body-attr%
+  ;; What attributes should be hung off of BODY?
+  '())
+;;  (list
+;;   (list "BGCOLOR" "#FFFFFF")
+;;   (list "TEXT" "#000000")))
+
+(define %generate-article-toc% 
+  ;; Should a Table of Contents be produced for Articles?
+  ;; If true, a Table of Contents will be generated for each 'Article'.
+  #t)
+
+(define %generate-part-toc% #t)
+
+(define %shade-verbatim%
+  #t)
+
+(define %use-id-as-filename%
+  ;; Use ID attributes as name for component HTML files?
+  #t)
+
+(define %graphic-default-extension% "png")
+
+
+</style-specification-body>
+</style-specification>
+
+<external-specification id="docbook" document="docbook.dsl">
+
+</style-sheet>