From e466ffc54dd5937d615db06a1b497efed87548a0 Mon Sep 17 00:00:00 2001 From: jfieber Date: Tue, 9 May 1995 23:19:47 +0000 Subject: The linuxdoc DTD used for the FreeBSD handbook and FAQ. Reviewed by: rgrimes Obtained from: Linux (with modification) --- share/sgml/FreeBSD/Makefile | 5 + share/sgml/FreeBSD/Makefile.inc | 3 + share/sgml/FreeBSD/doc/example.sgml | 135 +++++++ share/sgml/FreeBSD/doc/guide.sgml | 734 +++++++++++++++++++++++++++++++++++ share/sgml/FreeBSD/dtd/Makefile | 12 + share/sgml/FreeBSD/dtd/linuxdoc | 533 +++++++++++++++++++++++++ share/sgml/FreeBSD/dtd/linuxdoc.dec | 105 +++++ share/sgml/FreeBSD/lib/Makefile | 12 + share/sgml/FreeBSD/lib/linuxdoc.sty | 129 ++++++ share/sgml/FreeBSD/rep/Makefile | 13 + share/sgml/FreeBSD/rep/html.general | 106 +++++ share/sgml/FreeBSD/rep/html.mapping | 408 +++++++++++++++++++ share/sgml/FreeBSD/rep/html.math | 104 +++++ share/sgml/FreeBSD/rep/latex.general | 106 +++++ share/sgml/FreeBSD/rep/latex.mapping | 674 ++++++++++++++++++++++++++++++++ share/sgml/FreeBSD/rep/latex.math | 104 +++++ share/sgml/FreeBSD/rep/nroff.general | 112 ++++++ share/sgml/FreeBSD/rep/nroff.mapping | 638 ++++++++++++++++++++++++++++++ share/sgml/FreeBSD/rep/nroff.math | 114 ++++++ 19 files changed, 4047 insertions(+) create mode 100644 share/sgml/FreeBSD/Makefile create mode 100644 share/sgml/FreeBSD/Makefile.inc create mode 100644 share/sgml/FreeBSD/doc/example.sgml create mode 100644 share/sgml/FreeBSD/doc/guide.sgml create mode 100644 share/sgml/FreeBSD/dtd/Makefile create mode 100644 share/sgml/FreeBSD/dtd/linuxdoc create mode 100644 share/sgml/FreeBSD/dtd/linuxdoc.dec create mode 100644 share/sgml/FreeBSD/lib/Makefile create mode 100644 share/sgml/FreeBSD/lib/linuxdoc.sty create mode 100644 share/sgml/FreeBSD/rep/Makefile create mode 100644 share/sgml/FreeBSD/rep/html.general create mode 100644 share/sgml/FreeBSD/rep/html.mapping create mode 100644 share/sgml/FreeBSD/rep/html.math create mode 100644 share/sgml/FreeBSD/rep/latex.general create mode 100644 share/sgml/FreeBSD/rep/latex.mapping create mode 100644 share/sgml/FreeBSD/rep/latex.math create mode 100644 share/sgml/FreeBSD/rep/nroff.general create mode 100644 share/sgml/FreeBSD/rep/nroff.mapping create mode 100644 share/sgml/FreeBSD/rep/nroff.math (limited to 'share/sgml/FreeBSD') diff --git a/share/sgml/FreeBSD/Makefile b/share/sgml/FreeBSD/Makefile new file mode 100644 index 0000000..084125b --- /dev/null +++ b/share/sgml/FreeBSD/Makefile @@ -0,0 +1,5 @@ +# $Id:$ + +SUBDIR= dtd rep lib + +.include diff --git a/share/sgml/FreeBSD/Makefile.inc b/share/sgml/FreeBSD/Makefile.inc new file mode 100644 index 0000000..847d34b --- /dev/null +++ b/share/sgml/FreeBSD/Makefile.inc @@ -0,0 +1,3 @@ +# $Id:$ + +BINDIR?= /usr/share/sgml/FreeBSD diff --git a/share/sgml/FreeBSD/doc/example.sgml b/share/sgml/FreeBSD/doc/example.sgml new file mode 100644 index 0000000..a16b684 --- /dev/null +++ b/share/sgml/FreeBSD/doc/example.sgml @@ -0,0 +1,135 @@ + + + + +
+ + + +Quick SGML Example +<author>Matt Welsh, <tt/mdw@cs.cornell.edu/ +<date>v1.0, 28 March 1994 +<abstract> +This document is a brief example using the Linuxdoc-SGML DTD. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction + +<p> +This is an SGML example file using the Linuxdoc-SGML DTD. You can format it +using the command +<tscreen><verb> +$ format -Tnroff | qroff | pg +</verb></tscreen> +this will produce plain ASCII. You can also produce LaTeX, and (soon) HTML +and Texinfo. + +<sect>The source + +<p> +Looking at the source for this file will be instructive to show you how +to use many of the Linuxdoc-SGML constructs. You should also read the +<em/Linuxdoc-SGML User's Guide/, in the file <tt/guide.sgml/. + +The source looks and feels like LaTeX, as you can see. Paragraphs are +separated by blank lines, macros are enclosed in angle brackets. It's +quite simple. + +<sect>Some examples + +<p> +Here are examples of things that you'll be using in the source. First, +let's decend into a subsection: + +<sect1>This is a subsection + +<p> +As the header says. Note that you need to use the <tt/p/ command to +start the body of the section, after the <tt/sect1/ command. +Here's a subsubsection: + +<sect2>This is a subsubsection + +<p> +Right. 5 levels of sections are available. Use the commands +<tt/sect/, <tt/sect1/, <tt/sect2/, <tt/sect3/, and <tt/sect4/ to get them. +This document uses the <tt>article</> document style, which is +appropriate for HOWTOs and other docs; the <tt>report</> style (which +includes the <tt/chapt/ sectioning command) should be used for the LDP docs. + +<sect1>Example text + +<p> +All right, so you're typing along, and you want to show some example code, +or example I/O with a program, whatever. Use the <tt/code/ or <tt/verb/ +``environments'' for this, wrapped in a <tt/tscreen/ environment, as so: +<tscreen><verb> +This is an example verb environment. +</verb></tscreen> +As well as: +<tscreen><code> +This is an example code environment. +</code></tscreen> +The <tt/tscreen/ environment just sets the font to small type and +indents it nicely. It's not required for using <tt/verb/ or <tt/code/, +but I suggest that you do. + +The <em/Linuxdoc-SGML User's Guide/ explains what special characters you +can and can't use in the <tt/verb/ and <tt/code/ environments. + +<sect1><heading>Cross references<label id="test-ref"></> + +<p> +What about cross-references? This section has been marked with the +<tt>label</> command; using <tt>ref</> will provide a cross reference, +as in ``See Section <ref id="test-ref">'' for more. + +Right now cross-references don't work in the <tt/nroff/ translation for +plain ASCII. + +<sect1>Using fonts + +<p> +You want fonts, we got fonts. Of course these won't show up in the +plain ASCII text, but they all map into the various output formats: +<bf/boldface/, <em/emphasis/, <sf/sans serif/, <sl/slanted/, +<tt/typewriter/, and <it/italics/. + +<sect1>Lists + +<p> +Lists are easy as well. Just use the <tt/itemize/ element with the +<tt/item/ commands, seen here: +<itemize> +<item> This is a list. +<item> Nothing exciting about that. + <itemize> + <item> Multiple levels are supported as well. + <item> Again, that's no surprise. + </itemize> + <enum> + <item> Enumerated lists using <tt>enum</> also work. + <item> Description environments using <tt>descrip</> along + with <tt>tag</> are also available, as seen here. + </enum> + <descrip> + <tag/First item./ Here's one item. + <tag/Second item./ Here's another. + <tag/Third item./ Can we go for three? + </descrip> +<item> A final item to top it all off. +</itemize> + +This is just about everything that you need to get started with +writing SGML docs using the <tt/linuxdoc-sgml/ DTD. Please let me know +if you think something should be changed or added to this document. + +</article> diff --git a/share/sgml/FreeBSD/doc/guide.sgml b/share/sgml/FreeBSD/doc/guide.sgml new file mode 100644 index 0000000..65e4cca --- /dev/null +++ b/share/sgml/FreeBSD/doc/guide.sgml @@ -0,0 +1,734 @@ +<!-- This is a linuxdoc-sgml User's Guide, by Matt Welsh + See guide.txt or guide.dvi for formatted output. + (You need to read this before you can format the source!) +--> + +<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> + +<article> + +<title>Linuxdoc-SGML User's Guide +<author>Matt Welsh, <tt/mdw@sunsite.unc.edu/ +<date>v1.3, 7 June 1994 +<abstract> +This document is a user's guide to the linuxdoc-sgml formatting system, +an SGML-based text formatter which allows you to produce LaTeX, plain +ASCII, and HTML from a single source format. This guide documents +Linuxdoc-SGML version 1.1. +</abstract> + +<toc> + +<sect>Introduction + +<p> +This is a user's guide to the <tt/linuxdoc-sgml/ document +processing system, for use with Linux documentation. <tt/linuxdoc-sgml/ +is an SGML DTD (Document Type Definition) and set of ``replacement files'' +which convert the SGML to <tt/groff/, LaTeX, and HTML source. In the future, +<tt/linuxdoc-sgml/ will support <tt/texinfo/, as well as other +formats. + +<tt/linuxdoc-sgml/ is based heavily on the QWERTZ DTD by Tom Gordon, +<tt/thomas.gordon@gmd.de/. I have only made revisions to his DTD and +replacement files for use by Linux documentation. + +<tt/linuxdoc-sgml/ is not meant to be a general document-processing system. +Although it can be used for documents of many types, I have tailored it for +use by the Linux documentors in producing HOWTOs, FAQs, and (later) the +Linux Documentation Project manuals. Therefore, I have tweaked features +into and out of the system for this purpose. If you see a lack of generality +in the system, that is the reason. There's nothing binding <tt/linuxdoc-sgml/ +to Linux documentation, but all documents produced by the system will look +a certain way. If you want things to look differently I suggest that you use +a more generalized system such as the plain QWERTZ DTD. + +One of the goals of this system is to make documents easy to produce in +numerous formats. Until now, most Linux documentation has been produced +in plain ASCII through manual editing. A system like <tt/groff/ can take care +of the plain-text formatting, but that still doesn't give you HTML (for +use on the World Wide Web), LaTeX (for nicely printed documents), or +<tt/texinfo/. Therefore, if there are features missing from this system +that you would like, <em/please let me know!/ The idea is that we shouldn't +have to use a lot of hackery to produce good-looking docs in multiple formats. +The author should have to do as little as possible. + +<sect1>About this document + +<p> +This document is written using the <tt/linuxdoc-sgml/ DTD. It contains +more or less everything you need to know to write SGML docs with this +DTD. See <tt/example.sgml/ for an example of an SGML document that you +can use as a model for your own docs. + +<sect1>Why SGML? + +<p> +I chose SGML for this system because SGML is made specifically for translation +to other formats. SGML, which stands for Standard Generalized Markup Language, +allows you to specify the <em/structure/ of a document---that is, what kinds +of things make up the document. You specify the structure of a document with +a DTD (Document Type Definition). <tt/linuxdoc-sgml/ is one DTD that specifies +the structure for Linux HOWTOs and other docs. QWERTZ is another DTD; the +SGML standard provides DTD's for books, articles, and other generic document +types. + +The DTD specifies the names of ``elements'' within the document. An element +is just a bit of structure---like a section, a subsection, a paragraph, +or even something smaller like <em/emphasised text/. Unlike LaTeX, however, +these elements are not in any way intrinsic to SGML itself. The +<tt/linuxdoc-sgml/ DTD happens to define elements that look a lot like +their LaTeX counterparts---you have sections, subsections, verbatim +``environments'', and so forth. However, using SGML you can define any kind +of structure for the document that you like. In a way, SGML is like +low-level TeX, while the <tt/linuxdoc-sgml/ DTD is like LaTeX. + +Don't be confused by this analogy. SGML is <em/not/ a text-formatting system. +There is no ``SGML formatter'' per se. SGML source is <em/only/ converted +to other formats for processing. Furthermore, SGML itself is used only to +specify the document structure. There are no text-formatting facilities or +``macros'' intrinsic to SGML itself. All of those things are defined within +the DTD. You can't use SGML without a DTD---a DTD defines what SGML does. + +<sect1>How it works + +<p> +Here's how processing a document with SGML and the <tt/linuxdoc-sgml/ DTD +works. First, you need a DTD. I'm using the QWERTZ DTD which was produced, +originally, by a group of people who needed a LaTeX-like DTD. I've modified +the QWERTZ DTD to produce the <tt/linuxdoc-sgml/ DTD for our purposes. +The DTD simply sets up the structure of the document. A small portion of +it looks like this: +<tscreen><verb> +<!element article - - + (titlepag, header?, + toc?, lof?, lot?, p*, sect*, + (appendix, sect+)?, biblio?) +(footnote)> +</verb></tscreen> +This part sets up the overall structure for an ``article'', which is like +a ``documentstyle'' within LaTeX. The article consists of a titlepage +(<tt/titlepag/), an optional header (<tt/header/), an optional table of +contents (<tt/toc/), optional lists of figures (<tt/lof/) and tables +(<tt/lot/), any number of paragraphs (<tt/p/), any number of top-level +sections (<tt/sect/), optional appendices (<tt/appendix/), an optional +bibliography (<tt/biblio/) and footnotes (<tt/footnote/). + +As you can see, the DTD doesn't say anything about how the document should +be formatted or what it should look like. It just defines what parts make +up the document. Elsewhere in the DTD the structure of the +<tt/titlepag/, <tt/header/, <tt/sect/, and other elements are defined. + +You don't need to know anything about the syntax of +the DTD in order to write documents. I'm just presenting it so you know +what it looks like and what it does. You <em/do/ need to be familiar with +the document <em/structure/ that the DTD defines. If not, you might +violate the structure when attempting to write a document, and be very +confused about the resulting error messages. We'll describe the +structure of <tt/linuxdoc-sgml/ documents in detail later. + +The next step is to write a document using the structure defined by the +DTD. Again, the <tt/linuxdoc-sgml/ DTD makes documents look a lot like +LaTeX---it's very easy to follow. In SGML jargon a single document written +using a particular DTD is known as an ``instance'' of that DTD. + +In order to translate the SGML source into another format (such as LaTeX +or nroff) for processing, the SGML source (the document that you wrote) +is <em/parsed/ along with the DTD by (you guessed it) the SGML <em/parser/. +I'm using the <tt/sgmls/ parser by James Clark, <tt/jjc@jclark.com/, who +also happens to be the author of <tt/groff/. We're in good hands. +The parser (the executable <tt/sgmls/ simply picks through your document and +verifies that it follows the structure set forth by the DTD. It also spits out +a more explicit form of your document, with all ``macros'' and elements +expanded, which is understood by <tt/sgmlsasp/, the next part of the +process. + +<tt/sgmlsasp/ is responsible for converting the output of <tt/sgmls/ to +another format (such as LaTeX). It does this using <em/replacement files/, +which describe how to convert elements in the original SGML document into +corresponding source in the ``target'' format (such as LaTeX or <tt/nroff/). + +For example, part of the replacement file for LaTeX looks like: +<tscreen><verb> +<itemize> + "\\begin{itemize}" + +&etago;itemize> + "\\end{itemize}" + +</verb></tscreen> +Which says that whenever you begin an <tt/itemize/ element in the +SGML source, it should be replaced with +<tscreen><verb> +\begin{itemize} +</verb></tscreen> +in the LaTeX source. (As I said, elements in the <tt/linuxdoc-sgml/ DTD +are very similar to their LaTeX counterparts). + +So, to convert the SGML to another format, all you have to do is write +a new replacement file for that format that gives the appropriate +analogues to the SGML elements in that new format. In practice, it's not +that simple---for example, if you're trying to convert to a format that +isn't structured at all like your DTD, you're going to have trouble. In +any case, it's much easier to do than writing individual parsers and +translators for many kinds of output formats; SGML provides a generalized +system for converting one source to many formats. + +Once <tt/sgmlsasp/ has completed its work, you have LaTeX source which +corresponds to your original SGML document, which you can format using +LaTeX as you normally would. Later in this document I'll give examples +and show the commands used to do the translation and formatting. You can +do this all on one command line. + +But first, I should describe how to install and configure the software. + +<sect>Installation +<p> +The file <tt/linuxdoc-sgml.tar.gz/ contains everything that you need +to write SGML documents and convert them to LaTeX, nroff, and HTML. +In addition to this package, you will need one or both of the following: +<enum> +<item><tt/groff/. You <em/need/ version 1.08 or 1.09. Apparently some of +the margin-handling in <tt/groff/ is in a state of flux from version to +version; they both work, but you get slightly different results. +(Particularly, with 1.09 the left margin isn't indented two characters as +it is in 1.08. There is a way around it, but it looks terrible on 1.08. +Versions previous to 1.08 <em/will not work/. +You can get this from <tt/prep.ai.mit.edu/ in +<tt>/pub/gnu</tt>. There is a Linux binary version on <tt/sunsite/ as well. +You will need <tt/groff/ to produce plain ASCII from your SGML docs. +(TeX/LaTeX will be used to produce nicely-printed PostScript and .dvi). + +<item>TeX and LaTeX. This is available more or less everywhere; you should +have no problem getting it and installing it (there is a Linux binary +distribution on <tt/sunsite/). Of course, you only need TeX/LaTeX +if you want to format your SGML docs with LaTeX. So, installing TeX/LaTeX +is optional. See the section on the Linux HOWTO project below for how we'll +manage this vis-a-vis the Linux HOWTOs. + +<item>If you want to view the generated HTML, I suggest getting NCSA Mosaic +2.2 or later. + +</enum> +Neither of these are required by the SGML system, but I suggest that you get +one or the other in order to format your docs and verify that they look +all right before distributing them. + +<sect1>Installing the software + +<p> +The steps needed to install and configure the <tt/linuxdoc-sgml/ stuff are +as follows: + +<enum> +<item>First, unpack the tar file <tt/linuxdoc-sgml.tar.gz/ somewhere. +This will create the directory <tt/linuxdoc-sgml/ where all of the SGML +files live. It doesn't matter where you unpack this file; just don't +move things around within the <tt/linuxdoc-sgml/ directory. + +<item>Next, you need to compile the <tt/sgmls/ parser. In the +<tt>linuxdoc-sgml/sgmls-1.1</tt> directory, issue the commands: +<tscreen><verb> +$ make config.h +$ make +$ make install +$ make install.man +</verb></tscreen> +This should compile the parser and translator, and place the binaries +<tt/sgmls/, <tt/sgmlsasp/, and <tt/rast/ in <tt>linuxdoc-sgml/bin</tt>. +I suggest that you don't move those binaries from that location; instead, +make symlinks to them from <tt>/usr/local/bin</tt> or place +<tt>linuxdoc-sgml/bin</tt> on your path. (If you move things around +within the <tt/linuxdoc-sgml/ tree you'll have to edit a number of files +to get everything to cooperate again. Best to leave things as-is.) + +If things don't work try editing the <tt/Makefile/ in the <tt/sgmls-1.1/ +directory. I have it set to use <tt/gcc/ as the compiler, and use +rather malignant options. Compiles fine on Linux and sun-4 systems. + +This will also install man pages for the three binaries in +<tt>linuxdoc-sgml/man</tt>. You can move those or link them to your +regular man page tree, should you need them. + +<item>Edit the variables at the top of the scripts <tt/format/, <tt/qroff/, +<tt/preroff/, <tt/prehtml/, and <tt/qtex/ in <tt>linuxdoc-sgml/bin</tt>. +All you really need to edit is the value of the <tt>LINUXDOC</tt> +shell variable which gives the full pathname of the <tt>linuxdoc-sgml</tt> +directory. + +<item>In the <tt>html-fix</tt> directory, issue the commands: +<tscreen><verb> +$ make +$ make install +</verb></tscreen> +This will build <tt>fixref</tt> and <tt>html2html</tt>, which are post +processors for the HTML conversion, and place them in the <tt>bin</tt> +directory. + +</enum> + +If all went well, you should be ready to use the system. Just be sure +that <tt>linuxdoc-sgml/bin</tt> is on your path or you've linked the +files therein to your standard binary directories. Again, don't just copy +them somewhere else; the scripts expect to find each other in that +directory. + +<sect1>Testing it out + +<p> +You can now test the system. The <tt/format/ script takes an SGML +document as input and translates it to a given format. The <tt/qtex/ +script will process the output of <tt/format/ using LaTeX, and +<tt/qroff/ will process it using nroff. + +Let's say you have the SGML document <tt/foo.sgml/. You can translate +it to LaTeX, and produce PostScript output (via <tt/dvips/) with +the command: +<tscreen><verb> +$ format -T latex foo | qtex > foo.ps +</verb></tscreen> +Or, you can produce a DVI file using the <tt>-d</tt> switch with +<tt>qtex</tt>, as so: +<tscreen><verb> +$ format -T latex foo | qtex -d > foo.dvi +</verb></tscreen> + +If you want to produce plain ASCII, through <tt/groff/, use the command: +<tscreen><verb> +$ format -T nroff foo | qroff > foo.txt +</verb></tscreen> +Note that I have tailored the <tt/groff/ conversion for plain ASCII output. +(That is, I've removed page headers, page numbers, changed the margins, +and so on.) With some hacking you can produce PostScript and DVI from the +<tt/groff/ resulting from <tt/format/, but I suggest that you use LaTeX +for that instead. + +If you want to produce HTML, the procedure is a bit more complicated, +because of cross-references. Here's an example: +<tscreen><verb> +$ format -T html foo.sgml | prehtml | fixref > tmp.html +$ format -T html foo.sgml | prehtml >> tmp.html +$ cat tmp.html | html2html foo > foo.html +$ rm tmp.html +</verb></tscreen> +This will produce <tt>foo.html</tt>, as well as <tt>foo-1.html</tt>, +<tt/foo-2.html/, and so on---one file for each section of the document. +Run your WWW client on <tt>foo.html</tt>, which is the toplevel file. +Also make sure that all of the HTML files corresponding to your document +are in one directory, as they reference each other with local URLs. + +A good way to test this would be to run it on this file, +<tt/guide.sgml/. + +If you just want to capture your errors from the SGML conversion, +use something like +<tscreen><verb> +$ format -T nroff foo > /dev/null +</verb></tscreen> + +<sect1>Development note +<p> + +The HTML conversion is, at this time, rudimentary but adequate. In the +future there will be support for cross-references, navigation buttons, +external URLs, and the like. Something is better than nothing. :) + +Also, if you'd like to help me implement a texinfo (or plain Info) +conversion for Linuxdoc-SGML, let me know! As with HTML we'll have to +do some pre- and post-processing (which you supposedly shouldn't need with +SGML, ah well), but that's not a big issue. + +<sect>Writing Documents with <tt/linuxdoc-sgml/ + +<p> +For the most part, writing documents using the <tt/linuxdoc/ DTD is very +simple, and somewhat like LaTeX. However, there are some caveats to watch +out for. In this section I'll give an introduction on writing SGML docs. +See the file <tt/example.sgml/ for an SGML example document (and tutorial) +which you can use as a model when writing your own docs. Here I'm just going +to discuss the various features of SGML, but the source is not very +readable as an example. Instead, print out the source (as well as the +formatted output) for <tt/example.sgml/ so you have a real live case to +refer to. + +<sect1>Basic concepts + +<p> +Looking at the source of the example document, you'll notice right off +that there are a number of ``tags'' marked within angle brackets +(<tt><</tt> and <tt/>/). A tag simply specifies the beginning or end +of an element, where an element is something like a section, a paragraph, +a phrase of italicized text, an item in a list, and so on. Using a tag +is like using a LaTeX command such as <tt>\item</tt> or +<tt>\section{...}</tt>. + +As a simple example, to produce <bf>this boldfaced text</bf>, I typed +<tscreen><verb> +As a simple example, to produce <bf>this boldfaced text&etago;bf>, ... +</verb></tscreen> +in the source. <tt><bf></tt> begins the region of bold text, and +<tt>&etago;bf></tt> ends it. Alternately, use can use the abbreviated form +<tscreen><verb> +As a simple example, to produce <bf/this boldfaced text/, ... +</verb></tscreen> +which encloses the bold text within slashes. (Of course, you'll need to +use the long form if the enclosed text contains slashes, such as the +case with UNIX filenames). + +There are other things to watch out with respect to special characters +(that's why you'll notice all of these bizarre-looking ampersand +expressions if you look at the source; I'll talk about those shortly). + +In some cases, the end-tag for a particular element is optional. For +example, to begin a section, you use the <tt><sect></tt> tag, +however, the end-tag for the section (which could appear at the end of +the section body itself, not just after the name of the section!) +is optional and implied when you start another section of the same depth. +In general you needn't worry about these details; just follow the model +used in the tutorial (<tt/example.sgml/), and feel free to ask me if you +have any questions about the particulars. + +<sect1>Special characters + +<p> +Obviously, the angle brackets are themselves special characters in the +SGML source. There are others to watch out for. For example, let's say +that you wanted to type an expression with angle brackets around it, +as so: <tt><foo></tt>. In order to get the left angle bracket, you +must use the <tt>&lt</tt> element, which is a ``macro'' that expands +to the actual left-bracket character. Therefore, in the source, I typed +<tscreen><verb> +angle brackets around it, as so: <tt>&ero;lt;foo>&etago;tt>. +</verb></tscreen> +Generally, something beginning with an ampersand is a special macro. For +example, there's <tt/&percnt/ to produce <tt>%</tt>, +<tt/&verbar/ to produce <tt>|</tt>, and so on. For all +``special characters'' there exist these ampersanded-entities to represent +them. + +Usually, you don't need to use the ampersand macro to get a special +character, however, in some cases it is necessary. The most commonly used +are: +<itemize> +<item>Use <tt>&amp;</tt> for the ampersand (<tt>&</tt>), +<item>Use <tt>&lt;</tt> for a left bracket (<tt><</tt>), +<item>Use <tt>&gt;</tt> for a right bracket (<tt>></tt>), +<item>Use <tt>&etago;</tt> for a left bracket with a slash +(<tt>&etago;</tt>) +<item>Use <tt>&dollar;</tt> for a dollar sign (<tt>$</tt>), +<item>Use <tt>&num;</tt> for a hash (<tt>#</tt>), +<item>Use <tt>&percnt;</tt> for a percent (<tt>%</tt>), +<item>Use <tt>``</tt> and <tt>''</tt> for quotes, or use + <tt>&dquot</tt> for <tt>&dquot;</tt>. +</itemize> + +<sect1>Verbatim and code environments + +<p> +While we're on the subject of special characters, I might as well mention +the verbatim ``environment'' used for including literal text in the output +(with spaces and indentation preserved, and so on). The +<tt>verb</tt> element is used for this; it looks like the following: +<tscreen><verb> +<verb> + Some literal text to include as example output. +&etago;verb> +</verb></tscreen> +The <tt>verb</tt> environment doesn't allow you to use <em/everything/ +within it literally. Specifically, you must do the following within +<tt/verb/ environments. +<itemize> +<item>Use <tt>&ero;</tt> to get an ampersand, +<item>Use <tt>&etago;</tt> to get <tt>&etago;</tt>, +<item>Don't use <tt>\end{verbatim}</tt> within a <tt>verb</tt> +environment, as this is what LaTeX uses to end the <tt>verbatim</tt> +environment. (In the future, it should be possible to hide the underlying +text formatter entirely, but the parser doesn't support this feature yet.) +</itemize> +The <tt>code</tt> environment is much just like the <tt/verb/ environment, +except that horizontal rules are added to the surrounding text, as so: +<code> +Here is an example code environment. +</code> + +You should use the <tt/tscreen/ environment around any <tt/verb/ environments, +as so: +<tscreen><verb> +<tscreen><verb> +Here is some example text. +&etago;verb>&etago;tscreen> +</verb></tscreen> +<tt/tscreen/ is an envionment that simply indents the text and sets the +sets the default font to <tt/tt/. This makes examples look much nicer, both +in the LaTeX and plain ASCII versions. You can use <tt/tscreen/ +without <tt/verb/, however, if you use any special characters in your +example you'll need to use both of them. <tt/tscreen/ does nothing to +special characters. See <tt/example.sgml/ for examples. + +The <tt/quote/ environment is like <tt/tscreen/, except that it does +not set the default font to <tt/tt/. So, you can use <tt/quote/ for +non-computer-interaction quotes, as in: +<tscreen><verb> +<quote> +Here is some text to be indented, as in a quote. +&etago;quote> +</verb></tscreen> +which will generate: +<quote> +Here is some text to be indented, as in a quote. +</quote> + +<sect1>Overall document structure + +<p> +Before we get too in-depth with details, I'm going to describe the +overall structure of a document as defined by the <tt/linuxdoc/ DTD. +Look at <tt/example.sgml/ for a good example of how a document is set up. + +<sect2>The preamble + +<p>In the document ``preamble'' you set up things such as the title +information and document style. For a Linux HOWTO document this should +look like: +<tscreen><verb> +<!doctype linuxdoc system> + +<article> + +<title>The Linux Food-Processing HOWTO +<author>Norbert Ebersol, <tt/norbert@foo.com/ +<date>v1.0, 9 March 1994 +<abstract> +This document describes how to connect your Linux machine to a food-processor +for dicing vegetables. +&etago;abstract> + +<toc> +</verb></tscreen> + +The elements should go more or less in this order. The first line tells +the SGML parser to use the <tt/linuxdoc/ DTD. The <tt><article></tt> +tag forces the document to use the ``article'' document style. (The +original QWERTZ DTD defines ``report'' and ``book'' as well; I haven't +tweaked these for use with <tt/linuxdoc-sgml/. Just use <tt/article/ for +you SGML docs, for now.) + +The <tt/title/, <tt/author/, and <tt/date/ tags should be obvious; in the +<tt>date</tt> tag include the version number and last modification time of +the document. + +Thr <tt/abstract/ tag sets up the text to be printed at the top of the +document, <em/before/ the table of contents. If you're not going to +include a table of contents (the <tt/toc/ tag), you probably don't +need an <tt/abstract/. I suggest that all Linux HOWTOs use this same format +for the preamble, so that the title, abstract, and table of contents are +all there and look the same. + +<sect2>Sectioning and paragraphs + +<p>After the preamble, you're ready to dive into the document. The following +sectioning commands are available: +<itemize> +<item><tt/sect/: For top-level sections (i.e. 1, 2, and so on.) +<item><tt/sect1/: For second-level subsections (i.e. 1.1, 1.2, and so on.) +<item><tt/sect2/: For third-level subsubsections. +<item><tt/sect3/: For fourth-level subsubsubsections. +<item><tt/sect4/: For fifth-level subsubsubsubsections. +</itemize> +These are roughly equivalent to their LaTeX counterparts <tt/section/, +<tt/subsection/, and so on. + +After the <tt/sect/ (or <tt/sect1/, <tt/sect2/, etc.) tag comes the +name of the section. For example, at the top of this document, after +the preamble, comes the tag: +<tscreen><verb> +<sect>Introduction +</verb></tscreen> +And at the beginning of this section (Sectioning and paragraphs), there +is the tag: +<tscreen><verb> +<sect2>Sectioning and paragraphs +</verb></tscreen> + +After the section tag, you begin the body of the section. However, you +must start the body with a <tt><p></tt> tag, as so: +<tscreen><verb> +<sect>Introduction + +<p> +This is a user's guide to the <tt/linuxdoc-sgml/ document processing... +</verb></tscreen> +This is to tell the parser that you're done with the section title +and are ready to begin the body. Thereafter, new paragraphs are started +with a blank line (just as you would do in TeX). For example, +<tscreen><verb> +Here is the end of the first paragraph. + +And we start a new paragraph here. +</verb></tscreen> +There is no reason to use <tt><p></tt> tags at the beginning of +every paragraph; only at the beginning of the first paragraph after +a sectioning command. + +<sect2>Ending the document + +<p>At the end of the document, you must use the tag: +<tscreen><verb> +&etago;article> +</verb></tscreen> + +to tell the parser that you're done with the <tt/article/ element (which +embodies the entire document). + +</sect2> +<sect1>Cross-references<label id="cross-ref"> + +<p>Now we're going to move onto other features of the system. +Cross-references are easy. For example, if you want to make a +cross-reference to a certain section, you need to label that section +as so: +<tscreen><verb> +<sect1>Introduction<label id="sec-intro"> +</verb></tscreen> +You can then refer to that section somewhere in the text using the +expression: +<tscreen><verb> +See section <ref id="sec-intro" name="Introduction"> for an introduction. +</verb></tscreen> +This will replace the <tt/ref/ tag with the section number labelled +as <tt/sec-intro/. The <tt/name/ argument to <tt/ref/ is necessary for +<tt/nroff/ and HTML translations (at the moment). The <tt/nroff/ +macro set used by Linuxdoc-SGML does not currently support cross-references, +and it's often nice to refer to a section by name instead of number. + +For example, this section is <ref id="cross-ref" name="Cross-references">. + +There is also a <tt/url/ element for Universal Resource Locators, or +URLs, used on the World Wide Web. This element should be used to refer +to other documents, files available for FTP, and so forth. For +example, +<tscreen><verb> +You can get the Linux HOWTO documents from +<url url="http://sunsite.unc.edu/mdw/linux.html" + name="the Linux Documentation Project home page">. +</verb></tscreen> +The <tt/url/ argument specifies the actual URL itself. A link to the +URL in question will be automatically added to the HTML document. +The optional <tt/name/ argument specifies the text that should be anchored to +the URL (for HTML conversion) or named as the description of the +URL (for LaTeX and <tt/nroff/). If no <tt/name/ argument is given, the +URL itself will be used. + +For example, you can get the Linuxdoc-SGML package from +<url url="ftp://ftp.cs.cornell.edu/mdw/linuxdoc-sgml-1.1.tar.gz">. + +<sect1>Fonts + +<p>Essentially, the same fonts supported by LaTeX are supported +by <tt/linuxdoc-sgml/. Note, however, that the conversion to +plain ASCII (through <tt/groff/) does away with the font +information---I might hack up plain-ASCII representations of the +various fonts if the need arises. So, you should use fonts +as much as possible, for the benefit of the conversion to LaTeX. +But don't depend on the fonts to get a point across in the plain +ASCII version. + +In particular, the <tt/tt/ tag described above can be used to +get constant-width ``typewriter'' font which should be used for +all e-mail addresses, machine names, filenames, and so on. +Example: +<tscreen><verb> +Here is some <tt>typewriter text&etago;tt> to be included in the document. +</verb></tscreen> +Equivalently: +<tscreen><verb> +Here is some <tt/typewriter text/ to be included in the document. +</verb></tscreen> +Remember that you can only use this abbreviated form if the enclosed +text doesn't contain slashes. + +Other fonts can be achieved with <tt/bf/ for <bf/boldface/ and <tt/em/ +for <tt/italics/. Several other fonts are supported as well, but +I don't suggest you use them, because we'll be converting these +documents to other formats such as HTML which may not support them. +Boldface, typewriter, and italics should be all that you need. + +<sect1>Lists + +<p>There are various kinds of supported lists. They are: +<itemize> +<item><tt/itemize/ for bulleted lists such as this one. +<item><tt/enum/ for numbered lists. +<item><tt/descrip/ for ``descriptive'' lists. +</itemize> +Each item in an <tt/itemize/ or <tt/enum/ list must be marked +with an <tt/item/ tag. Items in a <tt/descrip/ are marked with <tt/tag/. +For example, +<tscreen><verb> +<itemize> +<item>Here is an item. +<item>Here is a second item. +&etago;itemize> +</verb></tscreen> +Looks like this: +<itemize> +<item>Here is an item. +<item>Here is a second item. +</itemize> +Or, for an <tt/enum/, +<tscreen><verb> +<enum> +<item>Here is the first item. +<item>Here is the second item. +&etago;enum> +</verb></tscreen> +You get the idea. Lists can be nested as well; see the example document +for details. + +A <tt/descrip/ list is slightly different, and slightly ugly, but +you might want to use it for some situations: +<tscreen><verb> +<descrip> +<tag/Gnats./ Annoying little bugs that fly into your cooling fan. +<tag/Gnus./ Annoying little bugs that run on your CPU. +&etago;descrip> +</verb></tscreen> +ends up looking like: +<descrip> +<tag/Gnats./ Annoying little bugs that fly into your cooling fan. +<tag/Gnus./ Annoying little bugs that run on your CPU. +</descrip> + +<sect1>Miscellany + +<p> +There are various other esoteric features in the system as well, most +of which you probably won't use. If you're curious, read the QWERTZ +User's Guide (from <tt/ftp.cs.cornell.edu/ in <tt>pub/mdw/SGML</tt>). +QWERTZ (and hence, <tt/linuxdoc/) supports many features such as +mathematical formulae, tables, figures, and so forth. I don't recommend +using most of these features in the Linux HOWTOs because they won't render +well in plain ASCII. If you'd like to write general documentation in +SGML, I suggest using the original QWERTZ DTD instead of the hacked-up +<tt/linuxdoc/ DTD, which I've modified for use particularly by the Linux +HOWTOs and other documentation. + +The bottom line is, <tt/linuxdoc-sgml/ supports many other features found +in the QWERTZ DTD, but I haven't necessarily tweaked them to work well +with <tt/linuxdoc-sgml/. If you encounter problems with any of them, +please let me know. + +<sect>The Linux HOWTO project + +<p>How does this tie into writing HOWTOs? First of all, I'd like to see +everyone eventually convert their HOWTOs to SGML using this DTD. This has +a number of advantages. First of all, it will allow you to just send me +the SGML source, which I'll convert to plain ASCII, TeX, whatever, for +posting and archiving. Also, it will give the HOWTOs a common look and feel; +any changes that I make to the DTD will be reflected in all of the HOWTOs. + +I have set up the <tt/linuxdoc/ DTD to have a certain look and feel. +If you want your document to look differently, please let me know, because +I'll need to make those changes in the DTD itself. That is, <em/do not/ +modify your version of the DTD or replacement files to get other features +in the system. We all must use the same DTD and replacement files or +this whole system will break down. If you find bugs in it, or have suggestions +for how we can change thing or add/modify features, let me know. I'll be +more than happy to accomodate you. + +</article> diff --git a/share/sgml/FreeBSD/dtd/Makefile b/share/sgml/FreeBSD/dtd/Makefile new file mode 100644 index 0000000..38b2e2e --- /dev/null +++ b/share/sgml/FreeBSD/dtd/Makefile @@ -0,0 +1,12 @@ +# $Id:$ + +FILES= linuxdoc linuxdoc.dec +NOOBJ= noobj + +all clean cleandir depend lint tags: + +afterinstall: + install -c -o ${BINOWN} -g ${BINGRP} -m 444 ${FILES} \ + ${DESTDIR}${BINDIR}/dtd + +.include <bsd.prog.mk> diff --git a/share/sgml/FreeBSD/dtd/linuxdoc b/share/sgml/FreeBSD/dtd/linuxdoc new file mode 100644 index 0000000..775d984 --- /dev/null +++ b/share/sgml/FreeBSD/dtd/linuxdoc @@ -0,0 +1,533 @@ +<!-- This is LINUXDOC.DTD, a hacked version of QWERTZ.DTD v1.3 + by Matt Welsh; modified from QWERTZ.DTD by Tom Gordon --> + +<!entity % emph + " em|it|bf|sf|sl|tt|cparam " > + +<!entity % index "idx|cdx" > + +<!-- url added by HG --> +<!entity % xref + " label|ref|pageref|cite|url|ncite " > + +<!entity % inline + " (#pcdata | f| x| %emph; |sq| %xref | %index )* " > + +<!entity % list + " list | itemize | enum | descrip " > + +<!entity % par + " %list; | comment | lq | quote | tscreen " > + +<!entity % mathpar " dm | eq " > + +<!entity % thrm + " def | prop | lemma | coroll | proof | theorem " > + +<!entity % litprog " code | verb " > + +<!entity % sectpar + " %par; | figure | tabular | table | %mathpar; | + %thrm; | %litprog; "> +<!element linuxdoc o o + (part | chapt | sect | article | report | + book | letter | telefax | slides | notes | manpage ) > + +<!entity % general system -- general purpose characters -- > +%general; +<!entity Ae 'Ä' > +<!entity ae 'ä' > +<!entity Oe 'Ö' > +<!entity oe 'ö' > +<!entity Ue 'Ü' > +<!entity ue 'ü' > +<!entity sz 'ß' > +<!element p o o (( %inline | %sectpar )+) +(newline) > +<!entity ptag '<p>' > +<!entity psplit '</p><p>' > + +<!shortref pmap + "&#RS;B" null + "&#RS;B&#RE;" psplit + "&#RS;&#RE;" psplit +-- '"' qtag -- + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar > + +<!usemap pmap p> +<!element em - - (%inline)> +<!element bf - - (%inline)> +<!element it - - (%inline)> +<!element sf - - (%inline)> +<!element sl - - (%inline)> +<!element tt - - (%inline)> +<!element sq - - (%inline)> +<!element cparam - - (%inline)> + +<!entity ftag '<f>' -- formula begin -- > +<!entity qendtag '</sq>'> + +<!shortref sqmap + "&#RS;B" null +-- '"' qendtag -- + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar > + +<!usemap sqmap sq > + +<!element lq - - (p*)> +<!element quote - - ((%inline; | %sectpar;)*, p*)+ > +<!element tscreen - - ((%inline; | %sectpar;)*, p*)+ > +<!element itemize - - (item+)> +<!element enum - - (item+)> +<!element list - - (item+)> + +<!-- What a mess. The following is here to clean up problems with + paragraph breaks in a descrip. I can think of cases where this might + break, but it seems to work. mdw --> + +<!shortref desmap + "&#RS;B" null + "&#RS;B&#RE;" ptag + "&#RS;&#RE;" ptag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "[" lsqb + "]" rsqb + "{" lcub + "}" rcub + "|" verbar > + +<!element descrip - - (tag?, p+)+ > +<!usemap desmap descrip> + +<!element item o o ((%inline; | %sectpar;)*, p*) > + +<!element tag - o (%inline)> +<!usemap global (list,itemize,enum)> +<!entity space " "> +<!entity null ""> + +<!-- +<!shortref bodymap + "&#RS;B&#RE;" ptag + "&#RS;&#RE;" ptag + '"' qtag + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> +--> + +<!element figure - - ((eps | ph ), caption?)> +<!attlist figure + loc cdata "tbp"> + +<!element eps - o empty > +<!attlist eps + file cdata #required> +<!element ph - o empty > +<!attlist ph + vspace cdata #required> + +<!element caption - o (%inline)> + +<!shortref oneline + "B&#RE;" space + "&#RS;&#RE;" null + "&#RS;B&#RE;" null +-- '"' qtag -- + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> + +<!usemap oneline tag> +<!usemap oneline caption> + +<!entity % tabrow "(%inline, (colsep, %inline)*)" > +<!element tabular - - + (%tabrow, (rowsep, hline?, %tabrow)*, caption?) > + +<!attlist tabular + ca cdata #required> + +<!element rowsep - o empty> +<!element colsep - o empty> +<!element hline - o empty> + +<!entity rowsep "<rowsep>"> +<!entity colsep "<colsep>"> + +<!shortref tabmap + "&#RE;" null + "&#RS;&#RE;" null + "&#RS;B&#RE;" null + "&#RS;B" null + "B&#RE;" null + "BB" space + "@" rowsep + "|" colsep + "[" ftag +-- '"' qtag -- + "_" thinsp + "~" nbsp + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub > + +<!usemap tabmap tabular> +<!element table - - (tabular, caption?) > +<!attlist table + loc cdata "tbp"> + +<!element code - - rcdata> +<!element verb - - rcdata> + +<!shortref ttmap -- also on one-line -- + "B&#RE;" space + "&#RS;&#RE;" null + "&#RS;B&#RE;" null + "&#RS;B" null + '#' num + '%' percnt + '~' tilde + '_' lowbar + '^' circ + '{' lcub + '}' rcub + '|' verbar > + +<!usemap ttmap tt> +<!entity % math system -- math symbols -- > +%math; +<!element mc - - cdata > +<!entity % sppos "tu" > +<!entity % fcs "%sppos;|phr" > +<!entity % fcstxt "#pcdata|mc|%fcs;" > +<!entity % fscs "rf|v|fi" > +<!entity % limits "pr|in|sum" > +<!entity % fbu "fr|lim|ar|root" > +<!entity % fph "unl|ovl|sup|inf" > +<!entity % fbutxt "(%fbu;) | (%limits;) | + (%fcstxt;)|(%fscs;)|(%fph;)" > +<!entity % fphtxt "p|#pcdata" > +<!element f - - ((%fbutxt;)*) > + +<!entity fendtag '</f>' -- formula end -- > + +<!shortref fmap + "&#RS;B" null + "&#RS;B&#RE;" null + "&#RS;&#RE;" null + "_" thinsp + "~" nbsp + "]" fendtag + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> + +<!usemap fmap f > + +<!element dm - - ((%fbutxt;)*)> +<!element eq - - ((%fbutxt;)*)> + +<!shortref dmmap + "&#RE;" space + "_" thinsp + "~" nbsp + "]" fendtag + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> + +<!usemap dmmap (dm,eq)> +<!element fr - - (nu,de) > +<!element nu o o ((%fbutxt;)*) > +<!element de o o ((%fbutxt;)*) > +<!element ll o o ((%fbutxt;)*) > +<!element ul o o ((%fbutxt;)*) > +<!element opd - o ((%fbutxt;)*) > +<!element pr - - (ll,ul,opd?) > +<!element in - - (ll,ul,opd?) > +<!element sum - - (ll,ul,opd?) > +<!element lim - - (op,ll,ul,opd?) > +<!element op o o (%fcstxt;|rf|%fph;) -(tu) > +<!element root - - ((%fbutxt;)*) > +<!attlist root + n cdata ""> +<!element col o o ((%fbutxt;)*) > +<!element row o o (col, (arc, col)*) > + +<!element ar - - (row, (arr, row)*) > +<!attlist ar + ca cdata #required > +<!element arr - o empty > +<!element arc - o empty > +<!entity arr "<arr>" > +<!entity arc "<arc>" > + +<!shortref arrmap + "&#RE;" space + "@" arr + "|" arc + "_" thinsp + "~" nbsp + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub > + +<!usemap arrmap ar > +<!element sup - - ((%fbutxt;)*) -(tu) > +<!element inf - - ((%fbutxt;)*) -(tu) > +<!element unl - - ((%fbutxt;)*) > +<!element ovl - - ((%fbutxt;)*) > +<!element rf - o (#pcdata) > +<!element phr - o ((%fphtxt;)*) > +<!element v - o ((%fcstxt;)*) + -(tu|%limits;|%fbu;|%fph;) > +<!element fi - o (#pcdata) > +<!element tu - o empty > + +<!usemap global (rf,phr)> +<!element def - - (thtag?, p+) > +<!element prop - - (thtag?, p+) > +<!element lemma - - (thtag?, p+) > +<!element coroll - - (thtag?, p+) > +<!element proof - - (p+) > +<!element theorem - - (thtag?, p+) > +<!element thtag - - (%inline)> + +<!usemap global (def,prop,lemma,coroll,proof,theorem)> +<!usemap oneline thtag> +<!entity qtag '<sq>' > + +<!shortref global + "&#RS;B" null -- delete leading blanks -- + -- '"' qtag -- + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> + +<!usemap global linuxdoc> +<!element label - o empty> +<!attlist label id cdata #required> + +<!-- ref modified to have an optional name field HG --> +<!element ref - o empty> +<!attlist ref + id cdata #required + name cdata "&refnam"> + +<!-- url entity added to have direct url references HG --> +<!element url - o empty> +<!attlist url + url cdata #required + name cdata "&urlnam" > + +<!element pageref - o empty> +<!attlist pageref + id cdata #required> +<!element comment - - (%inline)> +<!element x - - ((#pcdata | mc)*) > +<!usemap #empty x > + +<!-- Hacked by mdw to exclude abstract; abstract now part of titlepag --> +<!element article - - + (titlepag, header?, + toc?, lof?, lot?, p*, (part | sect)*, + (appendix, sect+)?, biblio?) +(footnote)> + +<!attlist article + opts cdata #IMPLIED> + +<!-- Hacked by mdw to exclude abstract; abstract now part of titlepag --> +<!element report - - + (titlepag, header?, toc?, lof?, lot?, p*, + (part | chapt)*, (appendix, chapt+)?, biblio?) +(footnote)> + +<!attlist report + opts cdata #IMPLIED> +<!element book - - + (titlepag, header?, toc?, lof?, lot?, p*, (part | chapt)*, + (appendix, chapt+)?, biblio?) +(footnote) > + +<!attlist book + opts cdata #IMPLIED> + +<!-- Hacked by mdw, abstract now part of titlepag --> +<!element titlepag o o (title, author, date?, abstract?)> +<!element title - o (%inline, subtitle?) +(newline)> +<!element subtitle - o (%inline)> +<!usemap oneline titlepag> +<!element author - o (name, thanks?, inst?, + (and, name, thanks?, inst?)*)> +<!element name o o (%inline) +(newline)> +<!element and - o empty> +<!element thanks - o (%inline)> +<!element inst - o (%inline) +(newline)> +<!element date - o (#pcdata) > + +<!usemap global thanks> + +<!element newline - o empty > +<!entity nl "<newline>"> + +<!-- Hacked by mdw --> +<!element abstract - o (%inline)> +<!usemap oneline abstract> + + +<!element toc - o empty> +<!element lof - o empty> +<!element lot - o empty> +<!element header - - (lhead, rhead) > +<!element lhead - o (%inline)> +<!element rhead - o (%inline)> +<!entity % sect "heading, header?, p* " > +<!element heading o o (%inline)> +<!element part - o (%sect, (chapt* | sect*))> +<!element chapt - o (%sect, sect*) +(footnote)> +<!element sect - o (%sect, sect1*) +(footnote)> +<!element sect1 - o (%sect, sect2*)> +<!element sect2 - o (%sect, sect3*)> +<!element sect3 - o (%sect, sect4*)> +<!element sect4 - o (%sect)> +<!usemap oneline (part,chapt,sect,sect1,sect2,sect3,sect4)> +<!element appendix - o empty > +<!element footnote - - (%inline)> +<!usemap global footnote> +<!element cite - o empty> +<!attlist cite + id cdata #required> + +<!element ncite - o empty> +<!attlist ncite + id cdata #required + note cdata #required> + + +<!element idx - - (#pcdata)> +<!element cdx - - (#pcdata)> + +<!element biblio - o empty> +<!attlist biblio + style cdata "linuxdoc" + files cdata ""> +<!element slides - - (slide*) > + +<!attlist slides + opts cdata "null"> +<!element slide - o (title?, p+) > +<!entity % addr "(address?, email?, phone?, fax?)" > + +<!element letter - - + (from, %addr, to, %addr, cc?, subject?, sref?, rref?, + rdate?, opening, p+, closing, encl?, ps?)> + +<!attlist letter + opts cdata "null"> + +<!element from - o (#pcdata) > +<!element to - o (#pcdata) > + +<!usemap oneline (from,to)> + +<!element address - o (#pcdata) +(newline) > +<!element email - o (#pcdata) > +<!element phone - o (#pcdata) > +<!element fax - o (#pcdata) > + +<!element subject - o (%inline;) > +<!element sref - o (#pcdata) > +<!element rref - o (#pcdata) > +<!element rdate - o (#pcdata) > + +<!element opening - o (%inline;) > +<!usemap oneline opening> + +<!element closing - o (%inline;) > +<!element cc - o (%inline;) +(newline) > +<!element encl - o (%inline;) +(newline) > + +<!element ps - o (p+) > + +<!element telefax - - + (from, %addr, to, address, email?, + phone?, fax, cc?, subject?, + opening, p+, closing, ps?)> + +<!attlist telefax + opts cdata "null" + length cdata "2"> + +<!element notes - - (title?, p+) > +<!attlist notes + opts cdata "null" > +<!element manpage - - (sect1*) + -(sect2 | f | %mathpar | figure | tabular | + table | %xref | %thrm )> + + +<!attlist manpage + opts cdata "null" + title cdata "" + sectnum cdata "1" > +<!shortref manpage + "&#RS;B" null +-- '"' qtag -- + "[" ftag + "~" nbsp + "_" lowbar + "#" num + "%" percnt + "^" circ + "{" lcub + "}" rcub + "|" verbar> + +<!usemap manpage manpage > +<!-- end of linuxdoc dtd --> diff --git a/share/sgml/FreeBSD/dtd/linuxdoc.dec b/share/sgml/FreeBSD/dtd/linuxdoc.dec new file mode 100644 index 0000000..c063aba --- /dev/null +++ b/share/sgml/FreeBSD/dtd/linuxdoc.dec @@ -0,0 +1,105 @@ + <!SGML "ISO 8879:1986" + + CHARSET + + BASESET "ISO 646:1983//CHARSET + International Reference Version (IRV)//ESC 2/5 4/0" + DESCSET + 0 9 UNUSED + 9 2 9 + 11 2 UNUSED + 13 1 13 + 14 18 UNUSED + 32 95 32 + 127 1 UNUSED + + BASESET "ISO Registration Number 100//CHARSET + ECMA-94 Right Part of Latin Alphabet Nr. 1//ESC 2/13 4/1" + DESCSET + 128 32 UNUSED + 160 96 32 + + + CAPACITY SGMLREF + + TOTALCAP 99000000 + ATTCAP 1000000 + ATTCHCAP 1000000 + AVGRPCAP 1000000 + ELEMCAP 1000000 + ENTCAP 1000000 + ENTCHCAP 1000000 + GRPCAP 1000000 + IDCAP 32000000 + IDREFCAP 32000000 + + SCOPE DOCUMENT + + SYNTAX + + SHUNCHAR CONTROLS 0 1 2 3 4 5 6 7 8 9 + 10 11 12 13 14 15 16 17 18 19 + 20 21 22 23 24 25 26 27 28 29 + 30 31 127 128 129 + 130 131 132 133 134 135 136 137 138 139 + 140 141 142 143 144 145 146 147 148 149 + 150 151 152 153 154 155 156 157 158 159 + + BASESET "ISO 646:1983//CHARSET + International Reference Version (IRV)//ESC 2/5 4/0" + DESCSET + 0 128 0 + + + FUNCTION + RE 13 + RS 10 + SPACE 32 + TAB SEPCHAR 9 + + NAMING + LCNMSTRT "" + UCNMSTRT "" + LCNMCHAR ".-" + UCNMCHAR ".-" + NAMECASE GENERAL YES + ENTITY NO + + DELIM GENERAL SGMLREF + SHORTREF SGMLREF + + NAMES SGMLREF + + QUANTITY SGMLREF + ATTCNT 256 + GRPCNT 253 + GRPGTCNT 253 + LITLEN 8092 + NAMELEN 44 + TAGLVL 100 + + FEATURES + MINIMIZE + DATATAG NO + OMITTAG YES + RANK NO + SHORTTAG YES + + LINK + SIMPLE NO + IMPLICIT NO + EXPLICIT NO + + OTHER + CONCUR NO + SUBDOC NO + FORMAL YES + + APPINFO + NONE +> + +<!-- + Reference Concrete Syntax modifications for the DocBook DTD, + Revision: 2.2.1 + --> diff --git a/share/sgml/FreeBSD/lib/Makefile b/share/sgml/FreeBSD/lib/Makefile new file mode 100644 index 0000000..666750a --- /dev/null +++ b/share/sgml/FreeBSD/lib/Makefile @@ -0,0 +1,12 @@ +# $Id:$ + +FILES= linuxdoc.sty +NOOBJ= noobj + +all clean cleandir depend lint tags: + +afterinstall: + install -c -o ${BINOWN} -g ${BINGRP} -m 444 ${FILES} \ + ${DESTDIR}${BINDIR}/lib + +.include <bsd.prog.mk> diff --git a/share/sgml/FreeBSD/lib/linuxdoc.sty b/share/sgml/FreeBSD/lib/linuxdoc.sty new file mode 100644 index 0000000..0a86c43 --- /dev/null +++ b/share/sgml/FreeBSD/lib/linuxdoc.sty @@ -0,0 +1,129 @@ +%% This is linuxdoc-qwertz.sty, for use with SGML-generated LaTeX +%% by Matt Welsh (mdw@sunsite.unc.edu) +%% +%% Based on linuxdoc.sty by Michael K. Johnson, and latex.tex by +%% Leslie Lamport. +%% +%% Modified by John Fieber <jfieber@freebsd.org> for the FreeBSD +%% Documentation Project. + +\typeout{Linux Documentation Style `linuxdoc, version 0.02 <6 May 1995>} + +% qwertz TeX macros + +\catcode`\"=12 +\sloppy +\newtheorem{definition}{Definition} +\newtheorem{proposition}{Proposition} +\newtheorem{lemma}{Lemma} +\newtheorem{corollary}{Corollary} +\newtheorem{theorem}{Theorem} +\newcommand{\mch}[1]{{\ifmmode#1 \else\(#1\)\fi}} +\newcommand{\lt}{{\ifmmode{<}\else{\verb+<+}\fi}} +\newcommand{\gt}{{\ifmmode{>}\else{\verb+>+}\fi}} +\newcommand{\verbar}{{\ifmmode{|}\else{\tt|}\fi}} +\newcommand{\idx}[1]{#1\index{#1}} +\newcommand{\cdx}[1]{#1\index{#1@{\tt #1}}} + +%%% GLOBAL LAYOUT THINGS + +\marginparwidth 0.0 in +\parindent 0.0 in +\topmargin -0.5 in +\textheight 8.5 in +\advance\headsep 2 ex +\advance\textheight -2 ex +\renewcommand{\baselinestretch}{1.14} +\addtolength{\parskip}{1.2 ex} + +%%% ONE-SIDED/TWO-SIDED DEPENDENCIES + +\if@twoside % ``book'' style was chosen + \oddsidemargin 0.0 in + \evensidemargin 0 in + \textwidth 6 in + \def\ps@headings{\let\@mkboth\markboth + \def\@oddfoot{}\def\@evenfoot{}% No feet. + \def\@evenhead{\protect\rule[-4pt]{\textwidth}{.5pt}\kern-\textwidth + \rm \thepage\hfil \bf \leftmark} % Left heading. + \def\@oddhead{\protect\rule[-4pt]{\textwidth}{.5pt}\kern-\textwidth + {\bf \rightmark}\hfil \rm\thepage} % Right heading. + \def\chaptermark##1{\markboth {{\ifnum \c@secnumdepth >\m@ne + \@chapapp\ \thechapter. \ \fi ##1}}{}}% + \def\sectionmark##1{\markright {{\ifnum \c@secnumdepth >\z@ + \thesection. \ \fi ##1}}}} + +\else % if not book style, then + \oddsidemargin 0.0 in + \evensidemargin\oddsidemargin + \textwidth 6.5 in + \def\ps@headings{\let\@mkboth\markboth + \def\@oddfoot{}\def\@evenfoot{}% No feet. + \def\@oddhead{\protect\rule[-4pt]{\textwidth}{.5pt}\kern-\textwidth + {\bf \rightmark}\hfil \rm\thepage} % Right heading. + \def\@evenhead\@oddhead + \def\chaptermark##1{\markboth {{\ifnum \c@secnumdepth >\m@ne + \@chapapp\ \thechapter. \ \fi ##1}}{}}% + \def\sectionmark##1{\markright {{\ifnum \c@secnumdepth >\z@ + \thesection. \ \fi ##1}}}} + +\fi + +%% Titlepage stuff + +\gdef\@title{} +\gdef\title#1{\gdef\@title{#1}} +\gdef\@date{} +\gdef\date#1{\gdef\@date{#1}} +\gdef\@author{} +\gdef\author#1{\gdef\@author{#1}} +\gdef\@abstract{} +\gdef\abstract#1{\gdef\@abstract{#1}} + +\def\maketitle{\thispagestyle{empty}\let\footnotesize\small% +\let\footnoterule\relax +%\setcounter{page}{0}% +%\null +%\vskip 3 in +\noindent +{\huge\sf \@title}\\ +\rule{\textwidth}{1mm}\\ +\mbox{} \@author\ \hfill \@date\ \\ +\vskip 1 ex +\noindent{\sf \@abstract} +\setcounter{footnote}{0}% +\gdef\@author{}\gdef\@title{}\gdef\@years{}\gdef\@abstract{} +\let\maketitle\relax} + +%% Needs to be here for the previous ps@headings defs to work. +\pagestyle{headings} + +%%% USEFUL MACROS + +\newcommand{\linux}{Linux} % Always use this when + % refering to the \linux\ + % operating system, like that. +\newcommand{\key}[1]{{\fbox{\small\tt #1}}} % Use this to mark keys, like + % \key{del} for the delete key. +\newcommand{\ret}{\fbox{\sf return}} % Special case for the return key. +\newcommand{\st}{\small\tt} % Small typewriter -- comes in handy. +%\newcommand{\lb}{{\tt\char '173}} % Left Brace '{' +%\newcommand{\rb}{{\tt\char '175}} % Right Brace '}' +\newcommand{\lbr}{$\langle$} % Left Bracket '<' +\newcommand{\rbr}{$\rangle$} % Right Bracket '>' +\newcommand{\bs}{{\tt\char '134}} % BackSlash '\' +\newcommand{\tm}{${}^{\mbox{\tiny\sf TM}}$} +\newcommand{\TM}{\tm} % TM trademark symbol in + % either case +\newcommand{\cparam}[1]{{\rm \lbr{\sl #1}\rbr}} + % Metavariables. + +%% define URL macro to handle the optional name argument +\def\url#1#2{{\em #2} {\tt (#1)}} + +%% the tscreen environment automatically goes into typewriter type, +%% but is otherwise like the screen environment + +\newenvironment{tscreen}% + {\begin{quote}\bgroup\small\tt}% + {\egroup\end{quote}} diff --git a/share/sgml/FreeBSD/rep/Makefile b/share/sgml/FreeBSD/rep/Makefile new file mode 100644 index 0000000..e1a112e --- /dev/null +++ b/share/sgml/FreeBSD/rep/Makefile @@ -0,0 +1,13 @@ +# $Id:$ + +FILES= html.general html.mapping html.math latex.general latex.mapping +FILES+= latex.math nroff.general nroff.mapping nroff.math +NOOBJ= noobj + +all clean cleandir depend lint tags: + +afterinstall: + install -c -o ${BINOWN} -g ${BINGRP} -m 444 ${FILES} \ + ${DESTDIR}${BINDIR}/rep + +.include <bsd.prog.mk> diff --git a/share/sgml/FreeBSD/rep/html.general b/share/sgml/FreeBSD/rep/html.general new file mode 100644 index 0000000..7aa9ecf --- /dev/null +++ b/share/sgml/FreeBSD/rep/html.general @@ -0,0 +1,106 @@ + +<!entity AElig sdata "Æ" > +<!entity Aacute sdata "Á" > +<!entity Acirc sdata "Â" > +<!entity Agrave sdata "À" > +<!entity Atilde sdata "Ã" > +<!entity Ccedil sdata "Ç" > +<!entity Eacute sdata "É" > +<!entity Egrave sdata "È" > +<!entity Euml sdata 'Ë' > +<!entity Iacute sdata "Í" > +<!entity Icirc sdata "Î" > +<!entity Igrave sdata "Ì" > +<!entity Iuml sdata 'Ï' > +<!entity Ntilde sdata "Ñ" > +<!entity Oacute sdata "Ó" > +<!entity Ocirc sdata "Ô" > +<!entity Ograve sdata "Ò" > +<!entity Oslash sdata "Ø" > +<!entity Uacute sdata "Ú" > +<!entity Ugrave sdata "Ù" > +<!entity Yacute sdata "Ý" > +<!entity aacute sdata "á" > +<!entity acirc sdata "â" > +<!entity aelig sdata "æ" > +<!entity agrave sdata "à" > +<!entity aring sdata "å" > +<!entity atilde sdata "ã" > +<!entity ccedil sdata "ç" > +<!entity eacute sdata "é" > +<!entity ecirc sdata "ê" > +<!entity egrave sdata "è" > +<!entity euml sdata 'ë' > +<!entity iacute sdata "í" > +<!entity icirc sdata "î" > +<!entity igrave sdata "ì" > +<!entity iuml sdata 'ï' > +<!entity ntilde sdata "ñ" > +<!entity oacute sdata "ó" > +<!entity ocirc sdata "ô" > +<!entity ograve sdata "ò" > +<!entity oslash sdata "ø" > +<!entity otilde sdata "õ" > +<!entity uacute sdata "ú" > +<!entity ucirc sdata "û" > +<!entity ugrave sdata "ù" > +<!entity yacute sdata "ý" > +<!entity yuml sdata 'ÿ' > +<!entity lt sdata "<" > +<!entity amp sdata "&" > +<!entity ero sdata "&" > +<!entity etago sdata "</" > +<!entity dquot sdata '"' > +<!entity num sdata "#" > +<!entity percnt sdata "%" > +<!entity quot sdata """ > +<!entity lpar sdata "(" > +<!entity rpar sdata ")" > +<!entity ast sdata "*" > +<!entity plus sdata "+" > +<!entity comma sdata "," > +<!entity hyphen sdata "‐" > +<!entity colon sdata ":" > +<!entity semi sdata ";" > +<!entity equals sdata "=" > +<!entity commat sdata "@" > +<!entity lsqb sdata "[" > +<!entity rsqb sdata "]" > +<!entity circ sdata "ˆ" > +<!entity lowbar sdata "_" > +<!entity lcub sdata "{" > +<!entity verbar sdata "|" > +<!entity rcub sdata "}" > +<!entity tilde sdata "~" > +<!entity bsol sdata "\" > +<!entity dollar sdata "$" > +<!entity nbsp sdata "~" > +<!entity emsp sdata " " > +<!entity ensp sdata " " > +<!entity thinsp sdata " " > +<!entity mdash sdata "—" > +<!entity ndash sdata "–" > +<!entity hellip sdata "…" > +<!entity Auml sdata 'Ä' > +<!entity auml sdata 'ä' > +<!entity Ouml sdata 'Ö' > +<!entity ouml sdata 'ö' > +<!entity Uuml sdata 'Ü' > +<!entity uuml sdata 'ü' > +<!entity szlig sdata "ß" > +<!entity gt sdata ">" > +<!entity sect sdata "§" > +<!entity para sdata "¶" > +<!entity copy sdata "(c)" > +<!entity iexcl sdata "¡" > +<!entity iquest sdata "¿" > +<!entity cent sdata "¢" > +<!entity pound sdata "£" > +<!entity times sdata "×" > +<!entity plusmn sdata "±" > +<!entity divide sdata "÷" > +<!entity not sdata "¬" > +<!entity mu sdata "μ" > +<!entity tm sdata "[TM]" > +<!entity urlnam sdata "<@@urlnam>" > +<!entity refnam sdata "<@@refnam>" > diff --git a/share/sgml/FreeBSD/rep/html.mapping b/share/sgml/FreeBSD/rep/html.mapping new file mode 100644 index 0000000..dd53e90 --- /dev/null +++ b/share/sgml/FreeBSD/rep/html.mapping @@ -0,0 +1,408 @@ + +% Converts qwertz files to html files ready for fixref and html2html. +% +% This file is R-Rated because of uglyness. +% +% -Magnus <magnus@ii.uib.no> + +<qwertz> +</qwertz> + +<article> +</article> + +<report> +</report> + +<book> +</book> + +<notes> +</notes> + +% Manual Pages are expected to be formatted using nroff (or groff), unless +% they are included as sections of other qwertz documents. + +<manpage> +</manpage> + +<titlepag> +</titlepag> + +<title> + "<@@title>" + + + + "

" + "

" + + + + + + + "

" + "

" + + " and " + + + + "Thanks " + + + + "

" + "

" + + + "
" + +