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

[Troy Henderson]

My apologies, but I replied instead of replying to all.  Below is my
message that I sent to Stephen instead of the entire group.

> 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.

When Karl asked me after PracticalTeX 2006 to take over maintenance of
the MetaPost manual, this is what I envisioned that we was thinking
about.  As such, I readily agreed.  However, it was soon clear that
"maintenance" involved many aspects of MetaPost that I was not yet
qualified to deal with.  That's why (if you've been wondering) you
haven't heard many responses from me regarding the manual.

I also submitted a "feature request" (#42) for MetaPost to have
more/better documentation.  It seems at this point that Stephen's
thoughts come back to this request.  Do we want our "showcase" to be
in the manual, or do we want it to be in another document?  My guess
is that we want it to be in another document since the manual
"belongs" to Hobby and such changes would create quite a different
document than what he probably envisioned.  Thoughts?

> 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.

I certainly have lots of examples (including many animations) and have
time to do this.  After all, this is what I both wanted to do and
thought I was agreeing to do when Karl asked me to maintain the
manual.  My thoughts, however, is that I could certainly use some help
and that we might even consider using a wiki (or similar) for the
showcase.  If we do this, then we might want the wiki to be
"officially" part of MetaPost (just as the manual is).  Thoughts?

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

With something like a wiki, users are naturally encouraged to add
content.  Perhaps if this is the way we want to go, then the wiki
would initially only allow several of us to add content, and once we
establish the "direction" of the wiki, then we start opening it up to
other users.

Troy