Attachment 45564 Details for Bug 70217 – sgml_diff

sgml_diff

sgml_diff (text/plain), 8.84 KB, created by Leonard Zettel on 2004-08-09 16:40:23 UTC

(hide)

Description:

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 @@
> Language.
> 
> In a nutshell (and apologies to any SGML purists in the audience that
>- are offended) SGML is a language for writing other languages.
>+ are offended) SGML is a language for describing the writing of other 
>+ languages.
> 
>- 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
>- not writing SGML (per se), but you are using a language that is
>+ 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
>+ not writing SGML (per se), but are using a language
> defined using SGML.
> 
>- 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.
>-
>- 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.
>+ Another language defined using SGML is "LinuxDoc". Originally
>+ created by the Linux documentation group, it was also adopted by the
>+ FreeBSD Documentation Project.
>+
>+ 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.
> 
>- For example, this is how you might write a brief paragraph in HTML
>+ For example, consider this paragraph in HTML
> (do not worry about the content, just look at the tags):
> 
> <pre><![ CDATA [
>@@ -52,43 +51,40 @@
> you can use <command>adduser</command>.</para>
> ]]></pre>
> 
>- 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.
>+ 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.
> 
>- There are a number of advantages to this more expressive form of
>- markup:
>+ There are advantages to this more expressive form of markup:
> 
> <ul>
> <li>It is not ambiguous or inconsistent. You do not spend time
> 	 thinking "Hmm, I need to show a filename, should I use 'tt', or 'b',
>-	 or 'em'?" Instead, you just use the right tag for the right
>-	 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.
>+	 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.
> </li>
> 
> <li>You stop thinking about the presentation of your document, and
> 	 instead concentrate on the content.
> </li>
> 
>- <li>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.</li>
>+ <li>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.</li>
> 
> <li>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.</li>
> </ul>
> 
>- If you are familiar with them, this is a bit like Microsoft&reg; Word
>+ This is a bit like Microsoft&reg; Word
> stylesheets, only vastly more powerful.
> 
>- Of course, with this power comes a price;
>+ Of course, this power comes at a price;
> 
> <ul>
> <li>Because the number of tags you can use is much larger, it takes
>@@ -102,59 +98,61 @@
> </ul>
> 
> 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.
>+ FAQ. That's changing; there's a project underway
>+ to convert to DocBook.
> 
> <h2>What if you don't know LinuxDoc/DocBook? Can you still
> contribute?</h2>
> 
> 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.
> 
> <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.
> 
>- 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.
>+ 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.
> 
> <h2>More information about SGML and DocBook?</h2>
> 
>- You should first read the <a 
>- href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/index.html">Documentation Project 
>- Primer</a>. This aims to be a comprehensive explanation of 
>- everything you need to know in order to work with the FreeBSD 
>- documentation.
>+ First read the <a 
>+ href="&base;/doc/en_US.ISO8859-1/books/fdp-primer/index.html">
>+	Documentation Project Primer</a>, intended to be a
>+	 comprehensive explanation of everything you need to know 
>+	 in order to work with the FreeBSD documentation.
> 
>- This is a long document, split in to many smaller files. You can
>+ 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">one
> large file</a>.
> 
> <dl>
> <dt><a
>-	 href="http://www.oasis-open.org/cover/sgml-xml.html">http://www.oasis-open.org/cover/sgml-xml.html</a></dt>
>+	 href="http://www.oasis-open.org/cover/sgml-xml.html">
>+	 http://www.oasis-open.org/cover/sgml-xml.html</a></dt>
> 
> <dd>The SGML/XML web page. Includes countless pointers to more
> 	 information about SGML.</dd>
> 
> <dt><a
>-	 href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</a></dt>
>+	 href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">
>+	 http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</a></dt>
> 
>- <dd>The "Gentle Introduction to SGML". Recommended reading for anyone 
>-	who wants to learn more about SGML from a beginners
>+ <dd>The "Gentle Introduction to SGML". Recommended for anyone 
>+	who wants to learn more about SGML from a beginner's
> 	 perspective.</dd>
> 
> <dt><a
> 	 href="http://www.oasis-open.org/docbook/">http://www.oasis-open.org/docbook/</a></dt>
> 
>- <dd>The DocBook DTD is maintained by OASIS. These pages are aimed
>+ <dd>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.
> 	</dd>

Actions: View

Attachments on bug 70217: 45564