Posted by
Tiago Ferreira-2 on
URL: http://imagej.273.s1.nabble.com/Update-and-survey-on-the-User-Guide-tp5006542.html
Hi,
Just to update you all on the status of the user guide:
First the good news: It seems to be a useful and popular resource, so we'd try to update
it to IJ v1.48/49.
Now the bad news: It will be very time-consuming to maintaing both editions (the .pdf and
the .html) using the strategy that has been used so far[1].
The issue is that (AFAIK) there is no TeX converter that is truly capable of converting
the guide seemingly into HTML (presumably because it is a rather complex document), and
the the inefficient "grepping"[1] we do to ensure a nice HTML layout breaks as soon as
something changes. This gives us 3 choices:
1) Keep things as they are but focus first on the pdf edition, and only update the html
once a finalized pdf is ready.
2) Drop the current typesetting strategy, and use something else more robust that can
be automated without much fiddling.
3) Stop the dual edition and drop one of them: i.e., either improve the HTML or the pdf
document.
Assuming that 3) is not really an option (or is it?), the easiest and fastest thing right
now (at least from my own point of view), would be a compromised option 2). E.g., at least
one approach[2] seems to work, and this is how the guide could look in the next release:
https://dl.dropboxusercontent.com/u/136719/testguide/guide.htmlRight now is just a sluggish file. The final result would load faster since it would be
split across multiple files. But it comes with side effects:
1) the guide would loose its current look-and-feel
2) URLs would be page-based, e.g.:
https://dl.dropboxusercontent.com/u/136719/testguide/guide.html#pf35 https://dl.dropboxusercontent.com/u/136719/testguide/guide.html#pf72What do you guys think?
Could you please let us know your thoughts?
-tiago
PS1: Something that may not be known: All the guide files are on GitHub[3]. There is also
an attempted markdown version[4] (and thus, a plain text one) if someone wants to
migrate it elsewhere.
PS2: There is a page on GitHub with suggestions on how to contribute[5]. Also, please know
that even without a reply, all the emails you have written pointing to errors in the
guide were noted.
[1]
https://github.com/tferr/IJ-guide/blob/master/README[2]
http://coolwanglu.github.io/pdf2htmlEX/[3]
https://github.com/tferr/IJ-guide/[4]
https://github.com/tferr/IJ-guide/blob/master/alt-versions/guide.md[5]
https://github.com/tferr/IJ-guide#contributing--
ImageJ mailing list:
http://imagej.nih.gov/ij/list.html