diff --git a/doc/sgml/README.txt b/doc/sgml/README.txt new file mode 100644 index 000000000..acce0f71b --- /dev/null +++ b/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 >> + + diff --git a/doc/sgml/hamlib-doc.dsl b/doc/sgml/hamlib-doc.dsl new file mode 100644 index 000000000..82b2ec107 --- /dev/null +++ b/doc/sgml/hamlib-doc.dsl @@ -0,0 +1,155 @@ + + + +]]> + + +]]> +]> + + + + + + + + + + + +;; ==================== +;; 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))) + + + + + + + + + +;; 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") + + + + + + + +