Re: feature freeze? (Re: [Announce] mutt-1.5.13 is out)
Hi,
* Thomas Roessler [06-08-14 21:38:29 +0200] wrote:
So, what else -- except for a bit more public exposure of this or
the next version -- do we need before 1.6 is ready?
As 1.4.x has been out there quite a long time without larger updates, I
assume the same will happen with 1.6.x.
Thus I think prior to releasing it we should put lots of work into the
manual. I don't really mean to change text (but we can do it, of
course) but making it consistent.
Things we should really take care of are listed below.
1) For adding variable documentation we should make sure that things are
documented consistently. Now there're some conflicts with $$$foo and
$$foo. Also, some extension to makedoc probably is a good idea (which I
hacked for muttng, too :): Add \fT...\fP to make certain text
typewriter. This can be used in examples and things like that. For
muttrc(5) this doesn't matter but for the HTML manual we have examples
in typewriter (in manual.xml.head) but those comming in from init.h
aren't. This is ugly.
2) We should decide for either way of talking about keys in the manual.
IIRC we have a mixture of ^G and C-G for Ctrl+G.
3) We should make sure that all things we have anchors for (commands,
options, etc.) are also linked to from other places. This isn't
consistently the case, IMHO.
I know this is lots of really boring work, and I'm willing to do some
portion of it.
For the latter two points I propose a patch/mechanism that enables us to
define whatever tags we want in the manual and from there produce valid
docbook (I think I've read some DocBook FAQ that says that DocBook
primarly is intended to generated, not written by humans :). This would
allow us to say just:
<mutt:optref>honor_followup_to</mutt:optref>
when we want to refer to a configuration option (XML is markup, so this
is what we should do in the first place) and have xslt write out the
name with link to the reference section, prepend a '$' sign, layout in
typewriter and add an entry in the index. If we ever wanted to change
that, no problem: there's only central definition of what <mutt:optref/>
expands to.
Once somebody went over the whole manual and did the conversion, things
should be fine and fully consistent, and improve maintaince in the
future.
If someone is interested in an early patch:
<http://user.cs.tu-berlin.de/~pdmef/mutt/patches/patch-1.5.12-cvs.pdmef.manualng.1.diff>
(which isn't fully correct anymore due to some merge problems; I'll
look into it in a few weeks, i.e. this is proof-of-concept only)
bye, Rocco
--
:wq!