Re: RFI: debiandoc-sgml V2
Hi,
Let me start by saying that I really appreciate the various requests for
enhancements for DebianDoc-SGML. It's good to know that my efforts are
appreciated.
I've stated in several emails some time ago that I consider the current
version (v1 if you will) to be more or less frozen from a DTD point of
view. There're one small enhancement planned (bug #145999 to support
lettered items in a list), but after that no more new stuff in the DTD.
The DebianDoc-SGML tool suite consists of the following parts:
- DTD
- back-ends
- scripts
- documentation
- supporting tools (e.g. the PO tools mentioned sometime ago)
and each of these parts will see improvements in v2.
The following new main features are planned for v2 of the DTD:
- figure
- table
- index
- glossary
but also
- an 'id' attribute for all elements
- i18n support (e.g. a <translation> tag, see TODO)
and what else seems useful to add. I definitely don't want to bloat the
DTD with features in the category "nice to have but not really needed".
There'll be also some tags which I consider depricated and will no longer
be in v2 of the DTD:
- <httpsite>
- <httppath>
- <ftpsite>
- <ftppath>
The <url> tag provides all the functionality we need to replace these.
As far as the back-ends are concerned the following three main changes are
planned (besides of course implementing the new features in the DTD):
- Better i18n support (see bug #146157) which basically comes down to
changing the current single word translations to complete terms (e.g.
'Chapter $number' instead of just 'Chapter'. That allows each locale
to indicate properly how things really ought to be.
- The plain text and overstrike text back-ends become increasingly harder
to maintain, let alone add all these new features. These back-ends will
be replaced by a single groff back-end.
- The return of the Lout back-end as a viable alternative to LaTex.
For the scripts I'm planning a complete reimplementation in Perl to leverage
more of the functionality available in various Perl modules (e.g. both long
and short versions of the command line options). I also would like to have
the intermediate scripts (saspconvert, sgmlspl) and the back-ends somewhat
better integrated to make it easier and clearer to add new functionality.
And I'm also contemplating moving the whole thing to using the Perl XML
modules (where the real action is).
The documentation definitely needs a complete rewrite, overhaul and most
important extension to cover not only the new features but also the scripts.
I'm not yet sure what to do with e.g. the PO tools.
Osamu Aoki (debian@aokiconsulting.com) wrote:
> Hi folks in d-doc@l.d.o,
>
> Since woody is practical freeze and debiandoc-sgml is very complete
> shape for the woody release, let me start a thread collecting wish list
> requests for debiandoc-sgml V2. (Hi, Ardo!!!)
Thanks!
> Before starting my mail, let me express extreme gratitude to Ardo who
> has done excellent work keeping it i10n issues fixed for ever despite
> annoying bugging from me.
>
Thanks again and you're more than welcome. Keep bugging me!
[snip]
> =======================================================================
> How debiandoc-sgml should evolve from user's view.
> -----------------------------------------------------------------------
>
> 1. Add tag to include images in documents, where ever possible.
>
> This can be accommodated by hacking <url ...> tag. <fig ...> tag is a
> one to come. ASAP, Ardo. Just implement for PDF and HTML(with script
> to choose indirect link based on file size and command line option).
This is the no.1 feature to be added to v2. One of the issues we've to
solve is which formats to we support (PNG, JPEG, GIF, etc.) and what to
do with text based output formats.
> 2. Add table capability.
>
> This one is easy to implement if you use external program such as w3m or
> links but ... this is not easy if you want to make a good one.
And that last one is exactly what I want to do.
> Most manual should come with nice table summary of key issues :)
>
> 3. SGML normalization.
>
> Normalizing SGML code. For example, <p> ... -> <p> ... </p>.
I'm not really sure what you mean here. I'm using Xemacs+psgml mode which
takes care of the normalization. Or do you mean in the DTD?
> 4. Debiandic-sgml to DocBook XML converter.
>
> I assume is is quite feasible for Ardo to make one by changing HTML
> converter.
I've been talking to Mark Johnson about that I think DebianDoc should be
positioned between DccBook-Lite and DocBook, and that we should provide
converters from DccBook-Lite to DebianDoc and from DebianDoc to DocBook
to allow projects to move to a more suitable DTD if their needs change.
> 5. Aesthetically right structure.
>
> Sorry, Ardo. Debiandoc-sgml creates ugly list in HTML.
>
> <list>
> <item>List-item-1
> <item>List-item-2
> <item>List-item-3
> </list>
>
> becomes,
>
> <ul>
> <li>
> List-item-1
> </li>
> </ul>
> <ul>
> <li>
> List-item-2
> </li>
> </ul>
> <ul>
> <li>
> List-item-3
> </li>
> </ul>
>
> It is more uglier with <enumlist> tags.
>
> This should creates:
>
> <ul>
> <li>
> List-item-1
> </li>
> <li>
> List-item-2
> </li>
> <li>
> List-item-3
> </li>
> </ul>
>
> I wonder why???
To get a better look&feel in HTML. If you look at PDF/PS and the text based
output you'll notice an empty line between list entries (except in compact
lists). HTML by default doesn't do this. Hence I turn each list entry into
its own list to force the empty line.
> Also, there was no way to continue numbering of <enumlist> numbering
> when it is started. Sometimes, you need to have some normal text
> inserted into listings.
Could you file a wishlist so this doesn't get lost?
> 6. I wish to have some translation framework implemented.
>
> Denis Barbier seems to be developing interesting tool but if it is
> integrated into debiandoc-sgml, it shall be nicer.
I agree.
> 7. Last but least. I would like to have converter from lazy and user
> friendly SGML->XML converter included. I want to write debiandoc SGML
> but want to have full access to XML tools.i For me, XML looks like
> P-code (Bite compiled UCSD Pascal).
Interesting idea. I was actually thinking about moving to XML somewhere
down the road.
All in all we can conclude there's still a lot to be done in DebianDoc land. :-)
Thanks,
Ardo
--
Ardo van Rangelrooij
home email: ardo@debian.org
home page: http://people.debian.org/~ardo
GnuPG fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: