On Tuesday, September 08, 1998 10:01 PM, Fred L. Drake [SMTP:fdrake@cnri.reston.va.us] wrote:
to this particular documentation set. I am very concerned about actually authoring in DocBook.
What are your concerns here? Richard --------------------------------------------- Richard Folwell RedBox Technologies, Email: richardf@redbox.net http://www.redbox.net Voice: +44 181 585 8565 Fax: +44 181 585 8665
On Tuesday, September 08, 1998 10:01 PM, Fred L. Drake wrote:
to this particular documentation set. I am very concerned about actually authoring in DocBook.
Richard Folwell writes:
What are your concerns here?
Richard, My primary concern here is in the volume of the DTD and some of the intricacies of things like indexing. The current LaTeX markup is fairly friendly to someone working on the index, making it reasonably easy to insert new entries. This includes things which should be visible at multiple points in the index, using \indexii, \indexiii, \indexiv. When I was working on the conversion script, I looked at the index-generating elements from DocBook at found them very verbose. Perhaps some form of tag omission or the use of empty tags (SGML only, not XML) can make it tolerable; I'd have to take another look at it to remember the specifics. I think it is very important to make authoring fairly comfortable. We may be able to use a DocBook variant for authoring, with more allowable tag omission, but I don't want to require a conversion stage or expensive tools. Authors should be able to use vi or notepad if that's what they want, and still not to have to do anything more than is currently needed to mark documents in LaTeX. I suspect that to maintain all the semantic codings from the current LaTeX markup, new elements would need to be added (or define values for the ROLE attribute). I'd personally prefer new elements over ROLE values to reduce the volume of the markup. -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191
fdrake@cnri.reston.va.us said:
I think it is very important to make authoring fairly comfortable.
Don't forget that writing a document is only a small piece of a document's life cycle; personally, I don't think that the verbose markup style of DocBook is therefore a big problem. On the other hand, it should be quite easy to edit with a SGML declaration/DocBook variant that allows absolutely minimal input and run it through 'sgmlnorm' (part of Jade) to get something to continue working on.
We may be able to use a DocBook variant for authoring, with more
I'd personally prefer new elements over ROLE values to reduce the volume of the markup.
Note that when adding new elements you need to provide DSSSL enhancements as well if you want to have them stand out in the final text. When using ROLE values, you'll generally have the correct rendition. Furthermore, you need to publish DTD fragments with the SGML source, and within some editing environments it may be cumbersome to load these DTD fragments in order to augment the environment for "python-enhanced DocBook". Especially in a setting like Python, where you cannot possibly predict what tools are going to be used to render/edit/... documents, you'll need to be very careful here. -- Cees de Groot http://pobox.com/~cg <cg@pobox.com> --- We're hiring Java developers => www.acriter.com
Fred L. Drake, Jr. said:
I think it is very important to make authoring fairly comfortable.
Cees de Groot writes:
Don't forget that writing a document is only a small piece of a document's life cycle; personally, I don't think that the verbose markup style of DocBook
Cees, This points to one of the quirks in the world of Python documentation: many sections are contributed (most especially in the library reference), but are maintained centrally after acceptance.
From that perspective, authoring needs to be easy since it is commonly done by people who only write a small number of sections. Maintenance is done by someone working on most of the documentation on a moderately regular basis (me), where the learning curve is more effectively ammortized. For the contributing author, there are typically no maintenance efforts, and if there are, it is usually accomplished by submitting a bug report.
Note that when adding new elements you need to provide DSSSL enhancements as well if you want to have them stand out in the final text. When using ROLE
I don't see this as a problem; I'd expect to provide at least one print and one online stylesheet for the system.
values, you'll generally have the correct rendition. Furthermore, you need to
Most of the semantic markings currently used produce a type-style change, so the style enhancements will be required one way or the other.
publish DTD fragments with the SGML source, and within some editing environments it may be cumbersome to load these DTD fragments in order to
I'm not terribly concerned about the ease of working with any of the commercially available SGML/XML editors, since those are usually too expensive to have hanging around, and I really don't expect many contributors already have them for other purposes. I don't know if emacs' PSGML mode would have difficulty with DocBook sub-/super-sets, which is more of an issue. I know vi and notepad would be ok. ;-) -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191
participants (3)
-
cg＠pobox.com -
Fred L. Drake -
Richard Folwell