Subject: Re: DSSSL Documentation Project From: Tony Graham <tgraham@xxxxxxxxxxxxxxxx> Date: Tue, 20 Jan 1998 14:16:14 -0500 (EST) |
At 20 Jan 1998 00:38 -0500, Paul Prescod wrote: > Ben Trafford wrote: > > I've had massive problems trying to use DSSSL with clients because of > > the lack of adequate documentation. I've also seen major software > > developers turn down the use of DSSSL because of that same lack. Look at > > what the Linux Free Documentation Project did for that platform! We > > could do the same for DSSSL. > > Note that the Linux Documentation Project did not write a book. They > essentially wrote many short tutorials and used hyperlinks and a central > index to glue them together. > > I am less confident than I was last year that it is feasible to write a > long, complicated, 21 chapter book over the Internet, using volunteers > and get something coherent out the other end. I'm also not as convinced > that we want to compete with prospective book authors like Ken. I am not > writing a DSSSL book, but I hope someone does. We developed an outline first so that we could be coherent and reduce the overlap in what various people wrote. Right now we have more than 400 potential reviewers reading this list, and I expect that if something is not coherent or not consistent, then someone will point it out; I don't think coherency is our problem. With no disrespect to Ken, just because Ken has said that he is writing a book on DSSSL doesn't mean that a group of us can't also write a book on DSSSL. The fact that someone once wrote a book on HTML doesn't seem to have stopped other people also writing books. This whole thing started because I figured that there were many people capable of writing good, useful stuff about DSSSL but that precious few of them had the time or resources to write a complete book. I am still of that opinion. At SGML/XML'97, I talked to two people who had told me back in June that they were writing DSSSL books. As of December, neither of them had had the spare time to get very far with their books. I do wish them well with their writing, but I think this illustrates my point. > I think that a more achievable goal would be to use the handbook outline > as a list of documents we would like completed, as the Linux people do. > We should then just link to the documents in the places where they > currently live. For instance, the first half part one is essentially my > tutorial (except I didn't write about the transformation language). Having documents scattered around the web makes the most sense if you have a fast, permanent Internet connection. Sometimes you want a local copy because you're not always connected or you connect only through a thin pipe, and for some people a lot of the time paper is better. > To complete "part one" we just need a crash course on Scheme (which I > think we can find on the web) and some annotated complex stylesheet > examples (which someone can do over a weekend). My argument is > that things get much easier if you just use them where they are. It also > keeps issues of ownership simple, cuts down on email attachment hassle, > might allow for some creative competition and avoids conversion to One > True DTD (which I have been putting off before submitting my tutorial to > the project). As I understand it, Linux documentation uses the "LinuxDoc" DTD and toolset, and that "LinuxDoc" tools have since been renamed "SGML-Tools". Marking up the DSSSL documentation with a single DTD makes the same sort of sense as standardising the Linux documentation did to the Linux folks. I think DocBook is a sensible choice because it is designed for software documentation and has elements like <programlisting>, <replaceable>, and <synopsis> as well as book-like elements like <chapter>, <preface>, and <legalnotice>. It makes additional sense for use with DSSSL because we already have, thanks to Jon Bosak and Norman Walsh, comprehensive and well-designed DSSSL stylesheets for both print and HTML output from the DocBook DTD. > As far as part 2, the two syntax summaries are essentially already done. > Debatably the spec. is its own refernce for many of the parts. It might > be most productive to zero in on the things people find most confusing. > > Part 3 seems very important to me, and could be handled either as an > "Advanced DSSSL Tutorial" or as a series of tutorials (the Linux project > calls these "HowTos"). In the short term, I think that the absolute > highest priority should be chapter 21 which describes how to use the > Jade SGML back-end to do SGML->SGML transforms. People want to use Jade > for web pages and I get questions about how to do that every few weeks > in email. A good tutorial on this would go a long way and would not be > very long. Since you don't appear to have that already but do know what it is that people want to know, do you want to write it? > I'm not suggesting we dissolve the project or anything like that, but > rather consider its main goal to be a *series* of tutorials and > reference manuals, maintained by their individual authors, which taken > together describe DSSSL as the various documents in the Linux > Documentation Project describe Linux. I have always hoped that the individual authors will maintain their contributions. I'll have to look at what I've said before, but I don't think that we're as far apart on this as you think, Paul. Regards, Tony Graham ======================================================================= Tony Graham Mulberry Technologies, Inc. Phone: 301-315-9632 17 West Jefferson Street, Suite 207 Fax: 301-315-8285 Rockville, MD USA 20850 email: tgraham@xxxxxxxxxxxxxxxx ======================================================================= DSSSList info and archive: http://www.mulberrytech.com/dsssl/dssslist
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: DSSSL Documentation Project, Ben Trafford | Thread | Re: DSSSL Documentation Project, Paul Prescod |
Re: DSSSL Documentation Project, Steve Roggenkamp | Date | Formatting an Address - a solution, Chuck Darney |
Month |