Plucker documentation update

[rsperberg]

I'm moving this discussion of improving the documentation to a new thread.

Roger:
What are the improved table-handling capabilities in the Python distiller?
Hacker:
Well, Plucker Desktop does not support tables (nor does JPluck or Sunrise), but the Python and C++ Plucker distillers do, when passed the --tables argument to the parsing commandline.

There are different ways we can handle this circumstance:

• I can notify you by email that the documentation doesn't have anything about tables.
• I (or anybody) can post a question in this forum and someone can sketch out an answer or point to a URI where the answer can/may be found.

If your grandmother is anything like me knowing that there is a --tables argument isn't enough to know what to do.

So I suggest that there be four levels in this documentation update:

1. Simple identification of an error or omission or discrepancy between the program's behavior and the documentation or confusion about the program's operation
2. Listing known differences between the latest version of the program and the documentation
3. An explanation describing a new feature
4. A complete segment suitable for adding to the public documentation

Personally, I'm only capable of steps 1 and 4, and I'm not yet knowledgeable to explore the program properly to do step 4 unless someone does step 3.

I guess I'm saying I need an education in the program before I can contribute in any substantive way, which inclines me towards using this forum to get steps 2 and 3 handled. I know you suggested sending email to you. Is there some alternative to piling more stuff in your inbox? I guess I'm thinking of how this might be handled in a wiki, though I'm not proposing setting up one.

Hm-m-m. Any other thoughts out there?

Roger

[hacker]

How about I set up a wiki that will allow the community to begin writing and fixing and adding the missing documentation pieces? Then take that and export it (unfortunately, manually) to a manual later? Would that be easier?

[rsperberg]

Well, it allows for multiple subjects to be developed simultaneously, at different paces.

So I'd say, yes, that would help a lot. That's just one opinion, mind you.

[rsperberg]

One more questions:

Was a document or list prepared of the type "New in version 1.8"? Each item on such a list would be a candidate for a page in the wiki, representing new material to be added to the existing documentation.

[hacker]

Ok, I've put up a Plucker Documentation wiki and populated it with sporadic pieces from the existing SGML documentation.

See what you can do with what is there, cut-n-paste the pieces over from ./docs to ./docwiki and update them as necessary. Move things around as you see fit, reorganize sections, make it flow easier, whatever you think would make sense as a proper "manual" for Plucker.

[rsperberg]

What a great wiki!

This is a great framework from which to start, and I'll assist with transferring the infromation as you suggest. I know that the structure of a wiki is something that grows organically -- I want to see pages on images and tables and such, that look at the issue of making pdb files from a different perspective -- as we cover both developer/serious user issues and novice matters.

Thanks for jumping right on this!

Roger

[hacker]

Originally Posted by rsperberg

What a great wiki! [...] Thanks for jumping right on this!

I aim to please...