Posted by
Jan Eglinger on
Feb 17, 2014; 4:59pm
URL: http://imagej.273.s1.nabble.com/Update-and-survey-on-the-User-Guide-tp5006542p5006556.html
Dear Tiago,
thank you for your great work creating and maintaining the ImageJ user
guide!
> 2) Drop the current typesetting strategy, and use something else
> more robust that can be automated without much fiddling.
>
Myself having used almost exclusively the HTML version of the guide, I
would be in favor of keeping this, and maybe even enhance the html
version in a way that provides clean and readable permanent URLs to the
current (most recent) version of all the sections (see [1] and [2]).
There are a lot of links on subsections of the user guide in forums like
this mailing list (just search for "docs/guide" in the list) and on
other forums like stackoverflow.com, so people looking there for help
might want to read the current version of the guide.
The current URL scheme includes the guide version (146), e.g.
http://rsbweb.nih.gov/ij/docs/guide/146-23.html#sub:ImageJ-Macro-Editorwhich is good for permanent linking, but will be outdated once a new
version is online. New users digging through the archives will profit
from an always-up-to-date URL scheme.
Best,
Jan
[1]:
http://en.wikipedia.org/wiki/Clean_URL[2]:
http://www.w3.org/Provider/Style/URIOn 16.02.2014, 11:01 PM, Tiago Ferreira 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