Re: debiandoc to docbook conversion situation full review (1st try)
Osamu Aoki <osamu@debian.org> writes:
> 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.
Ah I understand. A candidate for the real meaning of the tag, but
cannot be determined programmatically.
> > 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?
None that I know of.
> > > +---------------+---------------------------+-----------------------------+
> > > | file | filename class="?????????"| |
> > > | | filename class="directory"|
> > > |
FYI, I would guess we'll have to convert to just <filename> but then list
as an alternative <filename class="directory">.
> > > +---------------+---------------------------+-----------------------------+
> > > | strong | emphasis role="strong" | emphasis role="bold" |
> > > | | | (should it be alternative?) |
>
> Per Josip,
>
> | strong | emphasis role="strong" | |
possible alternative: important
> > > +---------------+---------------------------+-----------------------------+
> > > | 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?
I think it's reasonable to convert this to literal. Maintainer will
have to review this tag instance by instance. Possible alternatives:
constant
computeroutput
command (?, should have been prgn)
envar
function
keycap
keycode
keycombo
keysym
markup
option
parameter
prompt
property
returnvalue
sgmltag
symbol
token
userinput
varname
wordasword
> Maybe we should bring this to DDP CVS under /ddp/utils/debinadocsgml2xml
Yes. I think actually we should call it 'debian-docbook' or
'docbook-debian' and also be the place for putting the "standard
formatting" stylesheet. More on that in a separate email.
> > > +---------------+---------------------------+-----------------------------+
> > > | heading | title ? |
> > > |
> >
> > Depends on context, generally title, yes.
>
> What is possible alternative tags?
I don't think we ever need to worry about alternatives here. The XSLT
conversion should be able to handle every instance of this. I think
title is the only possible replacement, tho.
> > > +---------------+---------------------------+-----------------------------+
> > > | comment | comment |
> > > |
Um, docbook doesn't have <comment>. Do you mean remark ?
Possible alternatives:
caution
tip
warning
note
Actually I'm not sure if remark or note is more appropriate.
> > > +---------------+---------------------------+-----------------------------+
> > > | comment/p | phrase |
> > > |
You don't need to identify this separately. XSLT should handle the
para handling...
> By the way, I do not know what happens for the heading without <heading>
> tag.
It's an implied tag; before the XSLT gets to the SGML, it will be
normalized and the implied tags will be produced.
Can you regenerate the table and send it along?
--
...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>
Reply to: