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

Remove sgml.xml as well as links to the page. We no longer use SGML and

Browse source 
the FDP does a better job and providing an explanation.

Approved by:	bcr (mentor)
This commit is contained in:
Eitan Adler 2013-05-09 16:28:04 +00:00
parent 6aa41a56f0
commit a2fe031dc7
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=41577
3 changed files with 0 additions and 168 deletions
en_US.ISO8859-1/htdocs/docproj
Makefiledocproj.xmlsgml.xml

1
en_US.ISO8859-1/htdocs/docproj/Makefile
View file

@ -11,7 +11,6 @@ DOCS= current.xml
DOCS+= doc-set.xml
DOCS+= handbook.xml
DOCS+= handbook3.xml
DOCS+= sgml.xml
DOCS+= submitting.xml
DOCS+= who.xml
DOCS+= translations.xml

6
en_US.ISO8859-1/htdocs/docproj/docproj.xml
View file

@ -65,12 +65,6 @@
<p>This page outlines the components of the FreeBSD Documentation Set, and
the sort of work that the Documentation Project does with them.</p>
<h2><a href="sgml.html">SGML and the Documentation Project</a></h2>
<p>The project uses SGML for the documentation. This page
outlines how this is accomplished, and directs the interested reader to
further SGML resources.</p>
<h2><a href="submitting.html">Submitting Documentation</a></h2>
<p>Submitting documentation is the best way to become a part of the

161
en_US.ISO8859-1/htdocs/docproj/sgml.xml
View file

@ -1,161 +0,0 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
"http://www.FreeBSD.org/XML/doc/share/xml/xhtml10-freebsd.dtd" [
<!ENTITY title "FreeBSD Documentation Project: SGML">
]>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>&title;</title>
<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
</head>
<body class="navinclude.docs">
<p>The Documentation Project uses SGML as the standard method
of representing the documentation.</p>
<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 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
language used to write web pages, 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
defined using SGML.</p>
<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 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>
<pre><![CDATA[
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
this file you should use <b><tt>vipw</tt></b>. However, if you just
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
]]></pre>
<p>The same paragraph, marked up using DocBook, looks like</p>
<pre><![CDATA[
<para>The system's passwords are stored in
<filename>/etc/passwd</filename>. To edit this file you should use
<command>vipw</command>. However, if you just want to add a new user
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>There are a number of 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; elements 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&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
automatically produce an index of the documentation that lists every
command shown in the documentation.</p></li>
</ul>
<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>
<ul>
<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>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 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 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 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. 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>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.
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 page</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>
<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>
<dd><p>The "Gentle Introduction to SGML". Recommended reading 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
at users who are already comfortable with SGML, and
who want to learn DocBook.</p>
</dd>
</dl>
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
</body>
</html>