From owner-freebsd-doc@FreeBSD.ORG Tue Aug 3 19:38:23 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8058B16A4CE for ; Tue, 3 Aug 2004 19:38:23 +0000 (GMT) Received: from sccrmhc12.comcast.net (sccrmhc12.comcast.net [204.127.202.56]) by mx1.FreeBSD.org (Postfix) with ESMTP id 088EB43D3F for ; Tue, 3 Aug 2004 19:38:23 +0000 (GMT) (envelope-from zettel@acm.org) Received: from [192.168.0.6] (bgp966574bgs.derbrn01.mi.comcast.net[68.41.108.205]) by comcast.net (sccrmhc12) with ESMTP id <2004080319382201200fkerge>; Tue, 3 Aug 2004 19:38:22 +0000 From: Leonard Zettel To: freebsd-doc@freebsd.org Date: Tue, 3 Aug 2004 15:40:58 -0400 User-Agent: KMail/1.6.2 MIME-Version: 1.0 Content-Disposition: inline Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Message-Id: <200408031540.58469.zettel@acm.org> Subject: sgml.sgml modification proposal X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 03 Aug 2004 19:38:23 -0000 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 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: >Confidential: no >Synopsis: Suggested rewrite of docproj/sgml.sgml. >Severity: <[ non-critical | serious | critical ] (one line)> non-critical >Priority: <[ low | medium | high ] (one line)> low >Category: 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 >Description: The prose of sgml.html could be tightened up. >How-To-Repeat: Bring sgml.html up on any browser. >Fix: --- 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 @@ 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 - <...>) 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 <...>) 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):

adduser.
 ]]>
-

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:

  • 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®, and so on) makes sure that all <filename>'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®, and so on) makes sure that all <filename>'s + are shown the same way.

  • You stop thinking about the presentation of your document, and instead concentrate on the content.

    • -

  • 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.

    • +

  • 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.

  • 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.

-

If you are familiar with them, this is a bit like Microsoft® Word +

This is a bit like Microsoft® Word stylesheets, only vastly more powerful.

-

Of course, with this power comes a price;

+

Of course, this power comes at a price;

  • Because the number of tags you can use is much larger, it takes @@ -102,59 +98,61 @@

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.

What if you don't know LinuxDoc/DocBook? Can you still contribute?

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.

Submit 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.

More information about SGML and DocBook?

-

You should first read the Documentation Project - Primer. This aims to be a comprehensive explanation of - everything you need to know in order to work with the FreeBSD - documentation.

+

First read the + Documentation Project Primer, 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 one large file.

http://www.oasis-open.org/cover/sgml-xml.html
+ href="http://www.oasis-open.org/cover/sgml-xml.html"> + http://www.oasis-open.org/cover/sgml-xml.html

The SGML/XML web page. Includes countless pointers to more information about SGML.

http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html
+ href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"> + http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html -

The "Gentle Introduction to SGML". Recommended reading for anyone - who wants to learn more about SGML from a beginners +

The "Gentle Introduction to SGML". Recommended for anyone + who wants to learn more about SGML from a beginner's perspective.

http://www.oasis-open.org/docbook/
-

The DocBook DTD is maintained by OASIS. These pages are aimed +

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.

--- 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-