Return to BSD News archive
Path: sserve!newshost.anu.edu.au!harbinger.cc.monash.edu.au!simtel!zombie.ncsc.mil!news.mathworks.com!uhog.mit.edu!news.mtholyoke.edu!news.smith.edu!jfieber
From: jfieber@grendel.csc.smith.edu (John Fieber)
Newsgroups: comp.unix.bsd.freebsd.misc
Subject: Re: Documentation project (was Re: Slight flame from Linux user)
Date: 13 Jun 1995 17:04:49 GMT
Organization: Smith College, Northampton, MA, USA
Lines: 99
Message-ID: <3rkgfh$69g@sylvia.smith.edu>
References: <3ql3gd$je2@bell.maths.tcd.ie> <3rd8ki$76k@park.uvsc.edu> <3rhekp$400@hamilton.maths.tcd.ie> <3ri7d5$133@park.uvsc.edu>
NNTP-Posting-Host: grendel.csc.smith.edu
[note: my news source has been off in la-la-land so I missed the
beginning of this conversation.]
In article <3ri7d5$133@park.uvsc.edu>,
Terry Lambert <terry@cs.weber.edu> wrote:
>tim@maths.tcd.ie (Timothy Murphy) wrote:
>]
>] I assume that the "document sources" you are referring to
>] are those in the "handbook" directory.
>] [Would it have made it too easy to have said this ?]
>
>No, it would have made it difficult for me to have looked this
>up, since I do not consume the documentation.
>
>] There is no Makefile in this directory,
.
.
.
>I guess maybe ther is no Makefile because it is "The FreeBSD
>Documentation Project" rather than "The FreeBSD Documentation
>OnLine"... it's not done, quit complaining about the finish
>being too rough when it hasn't been painted yet.
Bingo!
>] [I may have been mistaken, but this Perl script
>] seemed to be for an old version of perl.
>] I found it necessary to replace '@@' throughout by '\@'.]
I'll look into this. I don't happen to have perl5 on my machine.
The script does work with the perl shipped with FreeBSD though.
>] >The FreeBSD SGML DTD's differences from the LinDoc DTD are calimed
>] >to be there because the LinDoc DTD is different from that expected
>] >by SGML using book publishers. Like O'Reilly.
>]
>] I don't think this is true.
>] All the FreeBSD programs seemed exact copies of the Linux ones
>] (developed to format the Linux HOWTOs),
>] which can be found in the Linux package linuxdoc-sgml.
>] The dtd used is actually called "linuxdoc"
>] (under Linux it is called "linuxdoc.dtd")
>] which hardly suggests a special FreeBSD product.
On the differences:
1) The DTD is essentially unchanged from the original
distribution. This is for compatibility. The only change I've
made to the DTD is to add a <part> tag to complete the sectioning
scheme. This will cause no problems processing older documents
or the Linux HOWTO's. That said, I think the linuxdoc DTD
provides a fairly good example of how NOT to write a DTD. I
considered making many other changes but they would break the
compatibility and I would rather spend time making a good
docbook->html conversion tool.
2) The changes were NOT made to be more compatible with the DTD
used by O'Reilly. The reason for not using the O'Rielly DTD to
begin with is (1) the lack of publically available formatting
tools and (2) the time involved in creating such a tool from
scratch, given the richness of the DTD.
3) The replacement and mapping files for the LaTeX and nroff
output are essentially the same. The replacement file for html
output has been changed to support the rewritten linuxdoc->html
conversion.
4) There were so many thing broken in the HTML generation as
provided in linuxdoc-sgml, that I rewrote it from the ground up.
The mechanism for generating all the formats certainly had that
"spit and bailing wire" feel to it which I've tried to erradicate
as much as possible.
5) The conversion should be re-written once again, using the
output from sgmls directly rather than using sgmlsasp.
6) The ascii output of linuxdoc-sgml sucks. The ascii output of
sgmlfmt sucks too.
>] But it is a bit rich to take Linux software, and then complain about it.]
I'm not , I just fixed some of the more gross bugs. I
would be happy for the linux camp to use my version.
>] In the latest linuxdoc-sgml package there are tools
>] for translating SGML files into HTML;
>] these seem to be missing from the FreeBSD version.
I beg your pardon? That functionality, formerly in the form of
several separate filters that had to manually be put together and
run in a particular sequence has been rolled into a single, easy
to use perl script. In the process, I've fixed more things that
were broken in the original version than I can count!
-john
--
=== jfieber@cs.smith.edu ================================================
=================================== Come up and be a kite! --K. Bush ===