One the one hand I agree with IOhannes that it's good to have the sources, on the other hand I also agree with Lucas that HTML suits itself very well for documentation. As he said, things like formulas can be included as images - which can be shipped as pre-built artifacts, or built from source, or both.
I would even go a bit further and say that it would be great if *all* Pd documentation was also available in HTML so it can be viewed in the browser and put on the homepage. IIRC, there is some plugin which converts Pd patches to SVG graphics, so that could be one way to go. In Supercollider, for example, all documentation is HTML, so you can read everything online: http://doc.sccode.org/. They also have their own small markup language for easy generation of class documentation. This is maybe not so relevant for Pd, as help files are just patches, but we could think about adding meta information to help files (e.g. short description, creation arguments, inlets, outlets), so we can autogenerate a short HTML reference/summary. Just thinking out loud. I have to say I really appreciate the documentation style of Supercollider and I think Pd could adapt some ideas. Christof > Gesendet: Montag, 01. Juli 2019 um 10:46 Uhr > Von: "IOhannes m zmoelnig" <[email protected]> > An: [email protected] > Betreff: Re: [PD-dev] formatting HTML doc in Pd distro? > > On 01.07.19 04:13, Lucas Cordiviola wrote: > > On 6/30/2019 10:41 PM, Miller Puckette wrote: > > > >> The gotcha is that I can't find a way to typeset equations in native > >> HTML... > > > > How about making the rendered image (of the math equation) with > > https://www.codecogs.com/latex/eqneditor.php and include the image in > > the HTML doc. (isn't this is what Latex do when it generates an HTML > > output ?) > > no, LaTeX doesn't rely on a 3rd party service eating all your data in > order to create nifty images. > > i *strongly* suggest to > - have **all** the sources (for *anything* generated, including images) > in the git-repository > - allow to build all artifacts automatically¹ (via the build-system) > > i'd prefer if the repository *only* contained the sources (and no > artifacts), but understand that it is sometimes impractical. > > > fgmasdr > IOhannes > > > ¹ unless *you* volunteer to become a build-bot waiting to upload LaTeX > sources to whatever webservice to create images in a timely manner. > > _______________________________________________ > Pd-dev mailing list > [email protected] > https://lists.puredata.info/listinfo/pd-dev > _______________________________________________ Pd-dev mailing list [email protected] https://lists.puredata.info/listinfo/pd-dev
