[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: DocBook 4.0: ClassSynopsis
/ "Fred L. Drake, Jr." <fdrake@acm.org> was heard to say: | Norman Walsh writes: | > - The "verbish" names have been made "nounish". Exception has | > been renamed ExceptionName, etc. Several of the elements will | > also be made available inline. | | But this is mixed. I understand the desire to make the names | similar to those of other, existing DocBook elements, but the lengthy | names are one of the reasons I don't see that DocBook is a good match | for my application (with lots of occaisional authors). While I sympathize (even with Epic at my disposal, I do occasionally edit DocBook documents "by hand" :-), DocBook has always attempted to select clear, meaningful element names in favor of short easy to type ones. (This is particularly important in a DTD with fairly broad international use.) It is really, IMHO, a tools issue. But I do sympathize. Honest. | > - A ClassSynopsisInfo element was added | | Perhaps this shows that I don't know enough about the existing | DocBook, but ... what is the indended use? Is this for a source-style | synopsis presentation as typically found in section 2 & 3 man pages? | (I'm presuming this based on the content model and %linespecific.attrib; | in the attribute list.) No, it's for "stuff that doesn't fit in the model". For example, in FuncSynopsis, it's how you can put a "#include" line in the synopsis. In ClassSynopsis, it's for other "verbatim" stuff that doesn't have semantic markup. It's an escape hatch. Consider the Perl case, which has "use" and "require" directives that are somewhat analagous to the #include in a funcsynopsis, you can use ClassSynopsisInfo for this: <classsynopsis language="perl"> <classname>DirHandle</classname> <classsynopsisinfo> require 5.000; use Carp; use Symbol; </classsynopsisinfo> <constructorsynopsis> <methodname>new</methodname> <methodparam choice="opt"><parameter>$dirname</parameter></methodparam> </constructorsynopsis> ... </classsynopsis> The fact that these elements end in "Info" is a bit unfortunate, but if that warrants fixing, we can fix them both in, um, 6.0. | I'll try and take a look when I have a few minutes. Hopefully this | week. -sigh- Thanks. I expect we won't get a final 4.0 candidate until mid-January, but the sooner we can get scrutiny on this proposal, the better. Cheers, norm -- Norman Walsh <ndw@nwalsh.com> | A new scientific truth does not http://www.oasis-open.org/docbook/ | triumph by convincing its Member, DocBook Editorial Board | opponents and making them see the | light, but rather because its | opponents eventually die, and a | new generation grows up that is | familiar with it (Planck 1949)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC