From root@zettel.us  Mon Aug  9 15:38:57 2004
Return-Path: <root@zettel.us>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 878E516A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  9 Aug 2004 15:38:57 +0000 (GMT)
Received: from zettel.us (bgp966574bgs.derbrn01.mi.comcast.net [68.41.108.205])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 898C743D3F
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  9 Aug 2004 15:38:49 +0000 (GMT)
	(envelope-from root@zettel.us)
Received: from zettel.us (localhost [127.0.0.1])
	by zettel.us (8.12.11/8.12.11) with ESMTP id i79Ffi5f000274
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 9 Aug 2004 11:41:44 -0400 (EDT)
	(envelope-from root@zettel.us)
Received: (from root@localhost)
	by zettel.us (8.12.11/8.12.11/Submit) id i79Ffik8000273;
	Mon, 9 Aug 2004 11:41:44 -0400 (EDT)
	(envelope-from root)
Message-Id: <200408091541.i79Ffik8000273@zettel.us>
Date: Mon, 9 Aug 2004 11:41:44 -0400 (EDT)
From: Leonard Zettel <Zettel@zettel.us>
Reply-To: Leonard Zettel <Zettel@zettel.us>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Suggested rewrite of docproj/sgml.sgml
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         70217
>Category:       docs
>Synopsis:       [patch] Suggested rewrite of docproj/sgml.sgml for clarification
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    remko
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 09 15:40:23 GMT 2004
>Closed-Date:    Thu Feb 21 19:26:36 UTC 2008
>Last-Modified:  Thu Feb 21 19:30:01 UTC 2008
>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@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
-      &lt;...&gt;) 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 &lt;...&gt;) 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&reg;, and so on) makes sure that all &lt;filename&gt;'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&reg;, and so on) makes sure that all &lt;filename&gt;'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&reg; Word
+    <p>This is a bit like Microsoft&reg; 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:
Responsible-Changed-From-To: freebsd-doc->remko 
Responsible-Changed-By: remko 
Responsible-Changed-When: Thu Jan 17 13:19:50 UTC 2008 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70217 
State-Changed-From-To: open->closed 
State-Changed-By: remko 
State-Changed-When: Thu Feb 21 19:26:35 UTC 2008 
State-Changed-Why:  
Two points committed, thanks for submitting this and the patience for 
waiting for them to get in! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=70217 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/70217: commit references a PR
Date: Thu, 21 Feb 2008 19:26:08 +0000 (UTC)

 remko       2008-02-21 19:26:04 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en/docproj           sgml.sgml 
   Log:
   Make some minor improvements to the docproj/sgml.sgml file.
   
   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>
   
   Revision  Changes    Path
   1.28      +3 -3      www/en/docproj/sgml.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
