Re: debiandoc to docbook conversion situation full review (1st try)
Hi,
On Tue, Dec 10, 2002 at 11:06:03AM -0600, Adam DiCarlo wrote:
> Osamu Aoki <osamu@debian.org> writes:
>
> > It will be nice if all these automatic translation table is completed
> > with alternative tag list. (This table shall be the part of "best
> > practice guide for debian DDP guideline to keep xml documents
> > consistent.) I am reading DebianDoc-SGML guide and...
> >
> > +---------------+---------------------------+-----------------------------+
> > | debiandoc tag | standard docbook-xml tag | alternative docbook-xml tag |
> > | (original) | (automatically translated) | (manually adjusted) |
> > +---------------+---------------------------+-----------------------------+
>
> What does the last column here mean?
I am thinking following scenario:
1) Use automatic script to convert to the tags in the middle column.
2) Since debiandoc tags tends to overload its meaning, I thought it may
be good idea for the editor to manually convert tags to one of the
better tags in last column if it is the case.
3) For new document, only the tags in either middle or last column are
recommended to be used (of course, image inserts and table needs to
be supported. That's a separate topic.) With this approach, we can
limit exposure to less than 50 tags.
> > | book | book | |
> > +---------------+---------------------------+-----------------------------+
> > | title | title | |
> > +---------------+---------------------------+-----------------------------+
> > | author | author | |
> > +---------------+---------------------------+-----------------------------+
> > | name | firstname+surname | |
> > +---------------+---------------------------+-----------------------------+
> > | email | email (only for author) | |
> > +---------------+---------------------------+-----------------------------+
> > | version | releaseinfo | |
> > +---------------+---------------------------+-----------------------------+
> > | abstract | abstract+para | |
> > +---------------+---------------------------+-----------------------------+
> > | copyright | copyright | |
> > +---------------+---------------------------+-----------------------------+
> > | toc | ??? (defined) | |
> > +---------------+---------------------------+-----------------------------+
>
> There is a docbook TOC tag.
>
> > | chapt | chapter | |
> > +---------------+---------------------------+-----------------------------+
> > | appendix | appendix | |
> > +---------------+---------------------------+-----------------------------+
> > | sect | sect1 | |
> > +---------------+---------------------------+-----------------------------+
> > | sect1 | sect2 | |
> > +---------------+---------------------------+-----------------------------+
> ...
>
> I personally disagree with using DocBook numbered sections. DocBook
> lets you nest <section> within <section> to the N-th degree. Using
> numbered <sectX> tags I think is gross. I believe they are deprecated
> in DocBook too and might go away.
That is much nicer. What is the negative of doing so?
> > | p | para | |
> > +---------------+---------------------------+-----------------------------+
> > | em | emphasis | |
> > +---------------+---------------------------+-----------------------------+
> > | strong | emphasis role="strong" | emphasis role="bold" |
> > | | | (should it be alternative?) |
Per Josip,
| strong | emphasis role="strong" | |
> > +---------------+---------------------------+-----------------------------+
> > | var | replaceable | |
> > +---------------+---------------------------+-----------------------------+
> > | package | systemitem role="package" | |
> > +---------------+---------------------------+-----------------------------+
> > | prgn | command | ? (what to use for well |
> > | | | known file) |
> > +---------------+---------------------------+-----------------------------+
> > | file | filename class="?????????"| |
> > | | filename class="directory"| |
> > +---------------+---------------------------+-----------------------------+
> > | tt | token | literal |
> > | | (is this constant width?) | type? (I see many use of tt |
> > |it can be: | | where type input are meant) |
> > |code | | ? |
> > |output fragment| | ? |
> > |command string | | ?
> > |
>
> Hmm, I change my mind, I think literal might be better. <token> is
> more specifical and <literal> more general, matching how <tt> is also
> more general.
<tt> is used inline command sequence while <example> is used as <screen>
in a separate line.
Can all code, output fragment, and command string be all <literal> or
some may need to be converted to alternative tags?
> As for whether something is rendered in proportional or fixed-width
> font, we shouldn't worry about that. That's a presentation issue, and
> we need to be more focussed on preserving structure and information.
>
> > +---------------+---------------------------+-----------------------------+
> > | qref | xref ???? |
> > |
>
> Wouldn't it be CITATION perhaps?
As I look at his new 0.8 version,
<qref> => <link>
<ref> => <xref>
(Funny he did not change <filename> yet?)
Maybe we should bring this to DDP CVS under /ddp/utils/debinadocsgml2xml
> > +---------------+---------------------------+-----------------------------+
> > | ref | xref | why not link?
> > |
>
> XREF is empty and LINK is not empty. Otherwise the tags are
> functionally identical. Since REF is debiandoc is always empty,
> right?, it seems to map to XREF.
>
> > +---------------+---------------------------+-----------------------------+
> > | manref | citerefentry | |
> > | | + refentrytitle | |
> > | | + manvolnum | |
> > +---------------+---------------------------+-----------------------------+
> > | ftpsite | (undefined) |
> > |
> Perhaps <systemitem class="systemname" role="ftpsite"> ?
>
> > +---------------+---------------------------+-----------------------------+
> > | ftppath | (undefined) | |
>
> Hmm. I would have to look at how this is rendered. Either <filename
> role="ftppath"> or a <ulink> if we can reasonable construct it.
>
> > +---------------+---------------------------+-----------------------------+
> > | httpsite | (undefined) | |
>
> Ditto ftpsite above.
>
> > +---------------+---------------------------+-----------------------------+
> > | httppath | (undefined) |
>
> Ditto ftppath above.
>
> > +---------------+---------------------------+-----------------------------+
> > | url | ulink | |
> > +---------------+---------------------------+-----------------------------+
> > | footnote | footnote | |
> > +---------------+---------------------------+-----------------------------+
> > | list | itemizedlist | |
> > +---------------+---------------------------+-----------------------------+
> > | enumlist | orderedlist | |
> > +---------------+---------------------------+-----------------------------+
> > | taglist | variablelist | |
> > +---------------+---------------------------+-----------------------------+
> > | list compact | (undefined) |
> > |
>
> itemizedlist spacing="compact"
>
> > +---------------+---------------------------+-----------------------------+
> > | enumlist compact | (undefined) |
> > |
>
> ditto
>
> > +---------------+---------------------------+-----------------------------+
> > | taglist compact | (undefined) |
>
> ditto
>
> > +---------------+---------------------------+-----------------------------+
> > | item | listitem |
> > |
>
> Generally listitem para I would imagine. May depend on context.
>
> > +---------------+---------------------------+-----------------------------+
> > | tag | varlistentry+tag ?? |
> > |
>
> Yup, I think so.
>
> > +---------------+---------------------------+-----------------------------+
> > | example | screen | literallayout |
> > +---------------+---------------------------+-----------------------------+
> >
> > Following tags are non-documented in debiandoc-sgml manual
> > +---------------+---------------------------+-----------------------------+
> > | heading | title ? |
> > |
>
> Depends on context, generally title, yes.
What is possible alternative tags?
>
> > +---------------+---------------------------+-----------------------------+
> > | comment | comment | |
> > +---------------+---------------------------+-----------------------------+
> > | comment/p | phrase | |
> > +---------------+---------------------------+-----------------------------+
> > | | | |
> > +---------------+---------------------------+-----------------------------+
> >
> > Are these use constant width fonts as default?
>
> Presentation issue, ignore that for now.
>
> > What criteria is used to choose <token> or <literal>
>
> Cf above.
>
> > Many short inline keyboard input uses <tt> as a tag. What tag is right
> > for these occasion?
>
> <command> I think
>
> > > > example -> literallayout : TT : screen
> >
> > I see more <example> used for <screen>. If not <screen>, we need to
> > adjust manually to <literallayout>
> >
> > > > heading -> (larger) : title
> > >
> > > Doesn't this get moved in Debiandoc2docbookxml to sectional titles?
> >
> > ???
>
> XSLT can be sensitive to the containing object.
By the way, I do not know what happens for the heading without <heading>
tag.
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki <osamu@debian.org> Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://qref.sf.net and http://people.debian.org/~osamu
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: