166 lines
6.9 KiB
Text
166 lines
6.9 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/en/docproj/sgml.sgml,v 1.19 2002/03/16 08:13:32 murray Exp $">
|
|
<!ENTITY title "FreeBSD Documentation Project: SGML">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>The Documentation Project is trying to use SGML as the standard method
|
|
of representing the documentation.</p>
|
|
|
|
<p>SGML is the <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
|
|
<b>L</b>anguage.</p>
|
|
|
|
<p>In a nutshell (and apologies to any SGML purists in the audience that
|
|
are offended) SGML is a language for writing other languages.</p>
|
|
|
|
<p>You have probably already used SGML, but you did not know it. HTML, the
|
|
language that web pages are written in, has a formal description. That
|
|
description is written in SGML. When you are writing HTML you are
|
|
<b>not</b> writing SGML (per se), but you are using a language that is
|
|
defined using SGML.</p>
|
|
|
|
<p>There are many, many markup languages that are defined using SGML. HTML
|
|
is one of them. Another is called "LinuxDoc". As you can probably guess,
|
|
it was originally created by the Linux documentation group to write
|
|
their documentation, and the FreeBSD Documentation Project adopted it as
|
|
well.</p>
|
|
|
|
<p>Another markup language defined using SGML is called "DocBook". This
|
|
is a language designed specifically for writing technical
|
|
documentation, and as such it has many tags (the things inside the
|
|
<...>) to describe technical documentation related things.</p>
|
|
|
|
<p>For example, this is how you might write a brief paragraph in HTML
|
|
(do not worry about the content, just look at the tags):</p>
|
|
|
|
<pre><![ CDATA [
|
|
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
|
|
this file you should use <b><tt>vipw</tt></b>. However, if you just
|
|
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
|
|
]]></pre>
|
|
|
|
<p>The same paragraph, marked up using DocBook, looks like</p>
|
|
|
|
<pre><![ CDATA [
|
|
<para>The system's passwords are stored in
|
|
<filename>/etc/passwd</filename>. To edit this file you should use
|
|
<command>vipw</command>. However, if you just want to add a new user
|
|
you can use <command>adduser</command>.</para>
|
|
]]></pre>
|
|
|
|
<p>As you can see, DocBook is much more 'expressive' than HTML. In the HTML
|
|
example the filename is marked up as being displayed in a 'typewriter'
|
|
font. In the DocBook example the filename is marked up as being a
|
|
'filename', the presentation of the filename is not described.</p>
|
|
|
|
<p>There are a number of advantages to this more expressive form of
|
|
markup:</p>
|
|
|
|
<ul>
|
|
<li><p>It is not ambiguous or inconsistent.</p> <p>You do not spend time
|
|
thinking "Hmm, I need to show a filename, should I use 'tt', or 'b',
|
|
or 'em'?"</p> <p>Instead, you just use the right tag for the right
|
|
job.</p>
|
|
|
|
<p>The conversion process from DocBook to other formats (HTML,
|
|
Postscript, and so on) makes sure that all <filename>'s are
|
|
shown the same way.</p>
|
|
</li>
|
|
|
|
<li><p>You stop thinking about the presentation of your document, and
|
|
instead concentrate on the content.</p>
|
|
</li>
|
|
|
|
<li><p>Because the documentation is not tied to any particular output
|
|
format, the same documentation can be produced in many different
|
|
formats - plain text, HTML, Postscript, RTF, PDF and so on.</p></li>
|
|
|
|
<li><p>The documentation is more 'intelligent', so more intelligent
|
|
things can be done with it. For example, it becomes possible to
|
|
automatically produce an index of the documentation that lists every
|
|
command shown in the documentation.</p></li>
|
|
</ul>
|
|
|
|
<p>If you are familiar with them, this is a bit like Microsoft Word
|
|
stylesheets, only vastly more powerful.</p>
|
|
|
|
<p>Of course, with this power comes a price;</p>
|
|
|
|
<ul>
|
|
<li><p>Because the number of tags you can use is much larger, it takes
|
|
longer to learn all of them, and how to use them effectively.</p>
|
|
|
|
<p>I found the best way to learn was to read the source to lots of
|
|
example documents, seeing how other authors had written similar
|
|
information.</p></li>
|
|
|
|
<li><p>The conversion process is not that simple.</p></li>
|
|
</ul>
|
|
|
|
<p>Right now, the Project is still using LinuxDoc for the Handbook and the
|
|
FAQ. That's changing, and in particular there's a project underway
|
|
to convert the documentation to DocBook.</p>
|
|
|
|
<h2>What if you don't know LinuxDoc/DocBook? Can you still
|
|
contribute?</h2>
|
|
|
|
<p>Yes you can. Quite definitely. Any documentation is better than no
|
|
documentation. If you've got some documentation to contribute and it's
|
|
not marked up in LinuxDoc or DocBook, don't worry.</p>
|
|
|
|
<p><a href="submitting.html">Submit</a> the documentation as
|
|
normal. Someone else on the Project will grab your committed
|
|
documentation, mark it up for you, and commit it. With a bit of luck
|
|
they'll then send you the marked up text back. This is handy because you
|
|
can do a "before and after" shot of the plain documentation and the
|
|
marked up stuff, and hopefully learn a bit more about the markup in the
|
|
process.</p>
|
|
|
|
<p>Obviously, this slows down the committing process, since your submitted
|
|
documentation needs to be marked up, which may take an evening or too.
|
|
But it will get committed.</p>
|
|
|
|
<h2>More information about SGML and DocBook?</h2>
|
|
|
|
<p>You should first read the <a
|
|
href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/index.html"><b>Documentation Project
|
|
Primer</b></a>. This aims to be a comprehensive explanation of
|
|
everything you need to know in order to work with the FreeBSD
|
|
documentation.</p>
|
|
|
|
<p>This is a long document, split in to many smaller files. You can
|
|
also view it as <a
|
|
href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>one
|
|
large file</b></a>.</p>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
|
|
|
<dd><p>The SGML/XML web page. Includes countless pointers to more
|
|
information about SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
|
|
|
<dd><p>The "Gentle Introduction to SGML". Recommended reading for anyone
|
|
who wants to learn more about SGML from a beginners
|
|
perspective.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
|
|
|
<dd><p>The DocBook DTD is maintained by OASIS. These pages are aimed
|
|
users who are already comfortable with SGML, and
|
|
who want to learn DocBook.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
|
&footer;
|
|
</body>
|
|
</html>
|