The thread on the PD documentation project seems to have died, and I presume that it is because no one is really sure how to go about it, or no one is willing to commit to actually steer it.
I am willing to put myself forward for some of the work, but as with anyone, my time is limited. Unless someone has a better idea, I would like to propose this following chain of actions.
documentation;
what outputs should the documentation be delivered as (HTML, RTF?, others?);
how should the documentation be indexed, markup'ed and stored (docbook? XML?)
what volumes/books/chapters should the documentation divided into [e.g.: book: PD chapter: pd syntax/principles (as per existing docs) chapter: object list (as per Max reference manual) book: GEM chapters... book: Source Code info chapter: how PD works chapter: how to compile PD subsection: how to solve the compilation problems in RH 7.x chapter: how to program externals book: specific subjects in PD (kind of like the Csound book) etc. ]
what existing documentation should be adapted/modified/recycled to fit in above
will supervise and adapt how the documentation is stored, modified, maintained, version'ed, etc.
reference
In a dream world, I would personally like to see a centrally maintained, always up-to-date, moderated on-line system, through which submissions can be made (with online forms, say); it would be beneficial to facilitate inline graphics (such as jpeg) for diagrams and screenshots; there should be automated links to object names and such; and there should be a way for people to annotate or add corrections online (and credit them of course.)
I have had a look at existing documentation projects and systems, and so far I haven't really found anything that does everything in one package. However it is obvious that XML should be the underlying format for storing the content of the documentation, although I don't see what the best way is to do that.
hi,
I am the one to blame, having started `pddp' thread, and then keeping silent for some time.
My original question was about a rather modest aim of building just a reference manual and appropriate tools. I have been thinking about it, and making some progress with the tools, very slowly. I have not written any content yet.
Very briefly: there is an external, clarify', which reports what classes can be created at any point of Pd session, what are their arguments, inlets, outlets, aliases, etc. The report may be coming from two sources: based on
espionage' tricks,
or taken from an external ``knowledge base''. What still needs
to be done, is finding a way to report differences between the
two sources (after all, `clarify' is meant to be basically
a maintenance tool...)
Such reports (and also the ``knowledge base'') are in a simple, troff-like format, to be processed with various scripts generating html, and (later) man, tex, maybe others. Have a look at
http://suita.chopin.edu.pl/~czaja/miXed/pddp/
-- those are just the templates, no contents, made with `bang' -> [clarify] in Pd, and then running a python script, without any editing (and without taking care of all the bugs...)
Anyway, to finish even the most basic of the tools I need to find some time for the coding -- it may happen, hopefully, end of this week.
Krzysztof
Dupras, Martin wrote:
The thread on the PD documentation project seems to have died, and I presume that it is because no one is really sure how to go about it, or no one is willing to commit to actually steer it.
Hi
( 02.05.21 17:09 +0100 ) Dupras, Martin:
The thread on the PD documentation project seems to have died, and I presume that it is because no one is really sure how to go about it, or no one is willing to commit to actually steer it.
Or because no one is going to DO it.
I'd suggest a better way to begin is to get material and *then* organize it. Let people send stuff to the list if they want, the important thing is to just get the material first. It can be polished/formatted later.
I still think pure-data.org is the best place for this. Maybe the webmaster there can put up the documents that get sent in.
My opinion is that all the talk about formats and such is a diversion from the actual work- namely writing stuff down [style over substance].