862bbd86d9
I didnt want to adopt everything because I dont entirely agree with everything, I only took out two changes that appear valid to me. PR: docs/70217 Submitted by: Leonard Zettel <Zettel at zettel dot us>
157 lines
6.6 KiB
Text
157 lines
6.6 KiB
Text
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/en/docproj/sgml.sgml,v 1.27 2006/08/19 21:20:33 hrs Exp $">
|
|
<!ENTITY title "FreeBSD Documentation Project: SGML">
|
|
<!ENTITY % navinclude.docs "INCLUDE">
|
|
]>
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>The Documentation Project uses SGML as the standard method
|
|
of representing the documentation.</p>
|
|
|
|
<p>SGML is the <b>S</b>tandard <b>G</b>eneralized <b>M</b>arkup
|
|
<b>L</b>anguage.</p>
|
|
|
|
<p>In a nutshell (and apologies to any SGML purists in the audience who
|
|
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 used to write web pages, 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 "DocBook". This is a language designed
|
|
specifically for writing technical documentation, and as such it has many
|
|
tags (the markers of the form <tt><tag content></tt>) to describe technical
|
|
documentation for subsequent formatting. The FreeBSD Documentation Project adopted
|
|
it and defined some new elements to make it more precise.</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> elements 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>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>A good way to learn SGML and DocBook is to read the source version of lots of
|
|
example documents, seeing how other authors have written similar
|
|
information.</p></li>
|
|
|
|
<li><p>The conversion process is not simple.</p></li>
|
|
</ul>
|
|
|
|
<h2>What if you do not know DocBook? Can you still
|
|
contribute?</h2>
|
|
|
|
<p>Yes you can. Quite definitely. Any documentation is better than no
|
|
documentation. If you have documentation to contribute and it is
|
|
not marked up in DocBook, do not 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 will 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 version 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. This may take a few hours spread
|
|
out over a few days, but it will get committed.</p>
|
|
|
|
<h2>More information about SGML and DocBook?</h2>
|
|
|
|
<p>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.
|
|
This is a long document, split into many smaller pages. You can
|
|
also view it as <a
|
|
href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>one
|
|
large page</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 beginner's
|
|
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
|
|
at 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>
|