FreeBSD Bugzilla – Attachment 45564 Details for
Bug 70217
[patch] Suggested rewrite of docproj/sgml.sgml for clarification
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
sgml_diff
sgml_diff (text/plain), 8.84 KB, created by
Leonard Zettel
on 2004-08-09 16:40:23 UTC
(
hide
)
Description:
sgml_diff
Filename:
MIME Type:
Creator:
Leonard Zettel
Created:
2004-08-09 16:40:23 UTC
Size:
8.84 KB
patch
obsolete
>--- 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>
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Raw
Actions:
View
Attachments on
bug 70217
: 45564