diff options
Diffstat (limited to 'share/sgml/FreeBSD/doc/guide.sgml')
| -rw-r--r-- | share/sgml/FreeBSD/doc/guide.sgml | 734 |
1 files changed, 734 insertions, 0 deletions
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> |
