docs/70217: Suggested rewrite of docproj/sgml.sgml
Leonard Zettel
Zettel at zettel.us
Mon Aug 9 15:40:24 UTC 2004
>Number: 70217
>Category: docs
>Synopsis: Suggested rewrite of docproj/sgml.sgml
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: sw-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Aug 09 15:40:23 GMT 2004
>Closed-Date:
>Last-Modified:
>Originator: Leonard Zettel
>Release: FreeBSD 4.10-RELEASE i386
>Organization:
>Environment:
System: FreeBSD zettel.us 4.10-RELEASE FreeBSD 4.10-RELEASE #0: Tue May 25 22:47:12 GMT 2004 root at perseus.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC i386
>Description:
>How-To-Repeat:
>Fix:
--- sgml_diff begins here ---
--- sgml.sgml_original Tue Aug 3 13:01:34 2004
+++ sgml.sgml Tue Aug 3 13:50:32 2004
@@ -15,26 +15,25 @@
<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>
+ are offended) SGML is a language for describing the writing of 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
+ <p>You have probably already used SGML, but did not know it. HTML, the
+ language used to write web pages, has a formal description written in
+ SGML. When you are writing HTML you are
+ <b>not</b> writing SGML (per se), but <b>are</b> using a language
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>Another language defined using SGML is "LinuxDoc". Originally
+ created by the Linux documentation group, it was also adopted by the
+ FreeBSD Documentation Project.</p>
+
+ <p>The SGML defined language "DocBook" is designed specifically for
+ writing technical documentation, and as such it has many tags
+ (the things inside the <...>) describing technical
+ documentation related things.</p>
- <p>For example, this is how you might write a brief paragraph in HTML
+ <p>For example, consider this paragraph in HTML
(do not worry about the content, just look at the tags):</p>
<pre><![ CDATA [
@@ -52,43 +51,40 @@
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>In HTML the filename is marked up as being displayed in a 'typewriter'
+ font. In DocBook the filename is marked up as being a
+ 'filename'. The presentation rules for a filename would be
+ described elsewhere.</p>
- <p>There are a number of advantages to this more expressive form of
- markup:</p>
+ <p>There are 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>
+ or 'em'?" but just use the right tag for the job.
+ 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>Because it is not tied to any particular format, the same
+ documentation can be produced in many different formats -
+ plain text, HTML, PostScript, RTF, PDF etc.</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
+ automatically produce an index 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
+ <p>This is a bit like Microsoft® Word
stylesheets, only vastly more powerful.</p>
- <p>Of course, with this power comes a price;</p>
+ <p>Of course, this power comes at a price;</p>
<ul>
<li><p>Because the number of tags you can use is much larger, it takes
@@ -102,59 +98,61 @@
</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>
+ FAQ. That's changing; there's a project underway
+ to convert 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
+ documentation. If you've got 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
+ they'll 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
+ marked up stuff, and hopefully learn a bit more about 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>
+ <p>This slows the committing process, since your documentation needs
+ to be marked up, which may take an evening or two.
+ 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>First read the <a
+ href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/index.html">
+ <b>Documentation Project Primer</b></a>, intended 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
+ <p>This is a long document, split into 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>
+ 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>
+ 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
+ <dd><p>The "Gentle Introduction to SGML". Recommended 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
+ <dd><p>The DocBook Document Type Definition (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>
--- sgml_diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list