sgml.sgml modification proposal
Leonard Zettel
zettel at acm.org
Tue Aug 3 19:38:23 UTC 2004
If y'all will be patient a minute with this newbie...
The material below was created with send-pr -P -a
and then hand edited.
---------------------------------------------------------
SEND-PR: -*- send-pr -*-
SEND-PR: Lines starting with `SEND-PR' will be removed automatically, as
SEND-PR: will all comments (text enclosed in `<' and `>').
SEND-PR:
SEND-PR: Please consult the following URL if you are not sure how to
SEND-PR: fill out a problem report:
SEND-PR: http://www.freebsd.org/doc/en/articles/problem-reports/
SEND-PR:
SEND-PR: Note that the Synopsis field is mandatory.
SEND-PR:
SEND-PR: Please note that (unless you state otherwise) if your report
SEND-PR: includes a patch then it will be taken under the same license as
SEND-PR: the one on the file(s) you want to change.
SEND-PR:
SEND-PR: BE ADVISED THAT FREEBSD PROBLEM REPORTS ARE PUBLIC INFORMATION AND
SEND-PR: WILL BE PUBLISHED AS-IS ON THE PROJECT'S MAILING LISTS AND WEB SITES.
SEND-PR: DO NOT SUBMIT ANY INFORMATION YOU DO NOT WANT MADE PUBLIC.
SEND-PR:
SEND-PR: If you wish to submit a problem report confidentially, then contact
SEND-PR: the FreeBSD bugmaster (bugmaster at FreeBSD.org) to arrange for a
SEND-PR: relevant developer to be contacted.
SEND-PR:
SEND-PR: For sensitive security issues, consider contacting the FreeBSD
SEND-PR: security officer team (security-officer at freebsd.org) directly.
SEND-PR:
SEND-PR: Choose from the following categories:
SEND-PR:
SEND-PR: advocacy alpha amd64 bin conf docs
SEND-PR: gnu i386 ia64 java kern misc
SEND-PR: ports powerpc sparc64 standards threads www
SEND-PR:
SEND-PR:
To: FreeBSD-gnats-submit at freebsd.org
From: Leonard Zettel <Zettel>
Reply-To: zettel at acm.org
Cc: zettel at acm.org
X-send-pr-version: 3.113
X-GNATS-Notify:
>Submitter-Id: current-users
>Originator: Leonard Zettel
>Organization: <organization of PR author (multiple lines)>
>Confidential: no <FreeBSD PRs are public data>
>Synopsis: <synopsis of the problem (one line)> Suggested rewrite of
docproj/sgml.sgml.
>Severity: <[ non-critical | serious | critical ] (one line)> non-critical
>Priority: <[ low | medium | high ] (one line)> low
>Category: <choose from the list of categories above (one line)> docs
>Class: <[ sw-bug | doc-bug | change-request | update | maintainer-update ]
(one line)> change-request
>Release: FreeBSD 4.10-RELEASE i386
>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
<machine, os, target, libraries (multiple lines)>
>Description:
<precise description of the problem (multiple lines)> The prose of sgml.html
could be tightened up.
>How-To-Repeat:
<code/input/activities to reproduce the problem (multiple lines)>Bring
sgml.html up on any browser.
>Fix:
<how to correct or work around the problem, if known (multiple lines)>
--- 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 ---
---------------------------------------------------------------
Will a subsequent send-pr -f sgml_pr
do what it is supposed to?
If not, what do I do instead?
Is it worth doing?
-LenZ-
More information about the freebsd-doc
mailing list