2009/3/14 Dominik Vogt <dominik.v...@gmx.de>: [...]
> As far as I remeber: > > * deb and rpm: We got bug reports that nobody took care of. > * html documentation: It's mostly unusable for me and way too > complex. There are be other, simpler ways to achive the same > benefits (asciidoc?). i'm trying not to muddy the waters with possible irrelevant conversation here, but I do agree with you on this -- I do find the documentation side of things a little cumbersome and I know for a fact there's much easier ways of handling this. I really *like* the idea behind having HTML documentation, don't get me wrong; the whole idea of it was always to split the documentation up into sections. I spent a long time at work last year putting together asciidoc and git for us devlopers to use for internal documentation with a fair amount of sucess. Whilst I can appreciate why in FVWM we're reliant on pure XML files to keep docbook happy, I wished there had been more discussion. Something like asciidoc would still do the same thing and have the advantage that: * It's all in plaintext. * There's no requirement to understand/learn XML. * The asciidoc markup is quite simple. The original requirement that kicked this change in documentation off was that for a while -- particularly on IRC and on the mailing lists, there was the question of "the manpage is too big", etc. Using something like asciidoc for plain-text readability when writing the documentation, the fact that it can be structured on a per-file basis for different sections, and that it can produce documentation in different output formats is all the better --- and note that for me, the main requirement for any documentation writing -- it should be in plain text first and foremost as much as possible. Alas, I do question though how easy it would be to change it now -- and I do know a lot of work went in to making it the way it is now. To undo all of that might seem like a slap in the face to people like Scott who did all the work originally. That said, if this is up for consideration, cool. [...] > * html documentation > > Became a part of fvwm because people spent a lot of work on it. > It is *the* top 1 reason why I don't write features anymore: > I'm simply unable to write the documentation anymore. I find this really sad. To think that one of core FVWM developers over the years no longer has any gumption to write new features because of the documentation? Well that surely has to change. Dominik, I assume (from my own experiences) that for you: * The overhead in understanding how the documentation fits together is high; * The requirement for using/learning XML is too much; Things like that? If not, I wonder what we might think about doing to help make this easier? > * FvwmGtk > > Dumped in fvwm without a discussion about the taken approach and > was never commented by any developers. A typical case of > accepting third party work in fvwm without a maintainer. This does bring about an interesting question: How do we handle the situation of maintaining FVWM modules which are in the CVS tree? It's different for the core of FVWM -- that's maintained differently, but a specific module? We can't rely or accept that the person submitting a module is the maintainer thereafter, although it would be nice. But people aren't always around for long, have other interests, real life kicks in, etc., so presumably the maintainership falls to whomever wants to do something with it at the time. Bar one or two, I would think almost all the modules in FVWM aren't "maintained" in that the original authors aren't here anymore. But that's OK, most of the modules in FVWM only use the FVWM <--> Module communication protocol, they're not reliant on anything else --- hence if we (as developers) ever broke anything, that's our problem to fix. Plus it makes understanding a given module much easier. But where you have modules reliant on third-party bits of software (anything written using perllib is a prime example here, although currently GTK is) that becomes a little more tricky. In the case of perl there's: * Looking out for major API changes in perl releases (perl 5.10 is hugely different to perl 5.8 -- and I would hate to see any perl 5.10 idioms ever make it into FVWM; you can't rely on its deployment on an aging SunOS machine for instance.) * Use of CPAN modules (FvwmTabs does this) -- what if a newer version shipped downstream by a distribution breaks due to some new subroutine call for instance? We're still responsible to fix it. * Having these extra CPAN modules is a requirement in order for the module to work. You could argue the last point is true of anything in the core -- i.e., if I wanted libstroke I would need to install it before I could make any mouse gestures --- but for a module this just seems wrong somehow. Plus, and this a bigee, here upstream, we are reponsible for all of this. We have a perllib API -- we are responsible for it, to make sure it doesn't break with the different facets of perl it's using. But this is almost "thrust" upon existing developers. Dominik, you obviously fall into this category: could you fix something in perllib or FvwmTabs if it broke? -- Thomas Adam
