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