Login  Register

Re: Update and survey on the User Guide

Posted by ph73nt on Feb 18, 2014; 8:22pm
URL: http://imagej.273.s1.nabble.com/Update-and-survey-on-the-User-Guide-tp5006542p5006568.html

Hi Tiago,

First of all great work! Second thing I'm sold on the PDF version, which I
think is a great positive for the IJ project and community. Lastly, which
tools have you tried for converting the LaTeX to HTML? I'd be happy to
invest some time investigating options, but obviously wouldn't want to
duplicate a failure.

Thanks for your time, Neil


On 16 February 2014 22:01, Tiago Ferreira <[hidden email]>wrote:

> 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.html
>
> Right 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#pf72
>
> What 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
>
>

--
ImageJ mailing list: http://imagej.nih.gov/ij/list.html