os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Changed various problems, mostly in wordage, including:

Browse source 
= Changed "purists...that" to "purists...who".
= Changed parenthetical explanation of "tags".
= Changed "added" to "defined" since elements were not added.
= Replaced awkward use of "related things".
= Changed awkward non-possessive "<filename>'s" to
  "<filename> elements".
= Removed too-restrictive "If you are familiar with them,".
= Reworded "I found the best way" from anonymous page.
= Removed "that" that referred to nothing.
= Changed "have got" to "have".
= Changed "they'll" to FDP's "they will".
= Changed too-informal "stuff" to "version".
= Removed erroneous "too" in small rewording that shortened a long
  sentence.
= Removed unnecessary "You should".
= Combined two paras on the same thing, changing "file" to "page".
= Inserted apostrophe in "beginners".
= Changed a quote char to an entity, twice.

Approved by:    keramida
This commit is contained in:
Gary W. Swearingen 2005-09-15 16:09:08 +00:00
parent 16e4ae5a49
commit 1725f77304
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=25652
1 changed files with 22 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
en/docproj/sgml.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$FreeBSD: www/en/docproj/sgml.sgml,v 1.23 2004/04/01 19:32:56 linimon Exp $">
<!ENTITY date "$FreeBSD: www/en/docproj/sgml.sgml,v 1.24 2005/03/02 00:48:42 keramida Exp $">
<!ENTITY title "FreeBSD Documentation Project: SGML">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
@ -14,7 +14,7 @@
<p>SGML is the <b>S</b>tandard <b>G</b>eneralized <b>M</b>arkup
<b>L</b>anguage.</p>
<p>In a nutshell (and apologies to any SGML purists in the audience that
<p>In a nutshell (and apologies to any SGML purists in the audience who
are offended) SGML is a language for writing other languages.</p>
<p>You have probably already used SGML, but you did not know it. HTML, the
@ -26,9 +26,9 @@
<p>There are many, many markup languages that are defined using SGML. HTML
is one of them. Another 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. The FreeBSD Documentation Project adopted
it and added some new elements to make it more precise.</p>
tags (the markers of the form <tt>&lt;tag&nbsp;content&gt;</tt>) to describe technical
documentation for subsequent formatting. The FreeBSD Documentation Project adopted
it and defined some new elements to make it more precise.</p>
<p>For example, this is how you might write a brief paragraph in HTML
(do not worry about the content, just look at the tags):</p>
@ -63,7 +63,7 @@
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
PostScript&reg;, and so on) makes sure that all &lt;filename&gt; elements are
shown the same way.</p>
</li>
@ -73,7 +73,7 @@
<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>
formats&mdash;plain text, HTML, PostScript, RTF, PDF and so on.</p></li>
<li><p>The documentation is more 'intelligent', so more intelligent
things can be done with it. For example, it becomes possible to
@ -81,7 +81,7 @@
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>
@ -90,44 +90,43 @@
<li><p>Because the number of tags you can use is much larger, it takes
longer to learn all of them, and how to use them effectively.</p>
<p>I found the best way to learn was to read the source to lots of
example documents, seeing how other authors had written similar
<p>A good way to learn SGML and DocBook is to read the source version of lots of
example documents, seeing how other authors have written similar
information.</p></li>
<li><p>The conversion process is not that simple.</p></li>
<li><p>The conversion process is not simple.</p></li>
</ul>
<h2>What if you do not know DocBook? Can you still
contribute?</h2>
<p>Yes you can. Quite definitely. Any documentation is better than no
documentation. If you have got some documentation to contribute and it is
documentation. If you have some documentation to contribute and it is
not marked up in DocBook, do not 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
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
they will then send you the marked-up text back. This is handy because you
can do a &quot;before and after&quot; shot of the plain documentation and the
marked up version and, hopefully, learn a bit more about the 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>
documentation needs to be marked up. This may take a few hours spread
out over a few days, but it will get committed.</p>
<h2>More information about SGML and DocBook?</h2>
<p>You should first read the <a
<p>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>This is a long document, split in to many smaller files. You can
documentation.
This is a long document, split into many smaller pages. 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>
large page</b></a>.</p>
<dl>
<dt><a
@ -140,7 +139,7 @@
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
who wants to learn more about SGML from a beginner's
perspective.</p></dd>
<dt><a