Re: debiandoc to docbook conversion situation full review (1st try)
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?
> | 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.
> | p | para | |
> +---------------+---------------------------+-----------------------------+
> | em | emphasis | |
> +---------------+---------------------------+-----------------------------+
> | strong | emphasis role="strong" | emphasis role="bold" |
> | | | (should it be alternative?) |
> +---------------+---------------------------+-----------------------------+
> | 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.
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?
> +---------------+---------------------------+-----------------------------+
> | 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.
> +---------------+---------------------------+-----------------------------+
> | 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.
--
...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>
Reply to: