[metapost] improving MetaPost documentation (was: [mp-implementors] [mpman] appendix A: withcolor and withprescript/withpostscript)

[Stephan Hennig]

Karl Berry schrieb:

> In general, the manual is not a work of art like, say, Knuth's books.

What I find much more unfortunate is that the MetaPost manual is not
nearly as attractive to the reader as alternative graphic packages,
c.f., the PGF/Beamer manual.  Being art-work or not.  The manual is far
too technical in the descriptions and examples and to less a tutorial.
There's to few fancy stuff like colours, patterns, shadings,
transparency, etc.  And tree diagrams, 3D graphics, animations are
missing, even though all of them should be possible with MetaPost.
Those are scattered around many packages with documentation varying in
style and extent.

How to improve on that?  I think what is missing is a unified MetaPost
show-case on top of individual package documentation.  That is,
tutorials that show solutions to real world problems and not simple
package documentation with academic examples.

I'm trying to do so in my packages (to some extend).  For example, in
the bpolynomial manual I show how to combine packages graph and
bpolynomial, metafun or hatching (maybe I should additionally move the
examples section to front before the actual manual sections).

I think the graph manual is a good example for how boring, boring,
boring a manual can look like.  But there are several other examples,
e.g., packages that provide documentation only as an ASCII text file.
Much room for improvements ...

How can the community help on that?  I ask for the community, because I
don't think the MetaPost development team has resources (time and
manpower) to do that.  IMHO, good documentation is a sign of a living
community.  Is MetaPost living?  And the community?  I'd not like to
answer the latter question.

How can we motivate the MetaPost community to tackle the documentation
problem?  Is there a documentation problem?

Best regards,
Stephan Hennig


PS:  For the next days I might only reply with a delay.