[Fluxus] documentation

[nik gaffney]

On 21/08/2019 12:54, Hong Yang wrote:
>
> For the document, I prefer to write it in some kind if more transparent way, such as MarkDown etc. By the way I can't find out the english revision of the reference manual any where in the repo.

It's been a while since i've looked at the fluxus documentation, but a few suggestions...

I agree that it should be easy to edit & update the docs and that it's also important to remain in sync with any changes in the code and/or interfaces. the docs in the current state have been very useful in providing examples, context (manual) and reference (function reference?). So, while the documentation should be editable (in some format) without having to build the project, it can also be generated at compile time e.g. to test examples, add the function reference from source, etc. 

so, some possible formats,

- markdown. well known, easy to write, update, translate. not so good for code examples & cross referencing

- scribble. designed for documenting racket projects, more syntax than .md perhaps higher threshold to editing but better code/text/reference integration. (see also 'pollen')

- org files. somewhere between markdown & scribble. easy to write, can produce various output formats (see :tangle) from a single literate style file.
 
- odt. easy to use, in document formatting, but not sure if there is much advantage over a simpler, text only format. 


as for output formats, html & pdf seems to cover it. all the text formats (md,scribble,org) can produce decent output but require slightly different paths e.g. md/org->pandoc->pdf/html or scribble->pdf/html (and html generated by libreoffice is a mess...)

I can't find the most recent fluxus docs in english, but if anyone has a recent enough version I'd be happy to convert it and sort out the output scripts.

nik

-- 
                                    [ f o a m ]  ->  http://fo.am
                                       grow your own worlds [借景]