Date: Tue, 3 Aug 2004 15:40:58 -0400 From: Leonard Zettel <zettel@acm.org> To: freebsd-doc@freebsd.org Subject: sgml.sgml modification proposal Message-ID: <200408031540.58469.zettel@acm.org>
next in thread | raw e-mail | index | archive | help
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@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@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@freebsd.org From: Leonard Zettel <Zettel> Reply-To: zettel@acm.org Cc: zettel@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@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-
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200408031540.58469.zettel>