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 [借景]
