Update and survey on the User Guide
Locked
Update and survey on the User Guide
 
|
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 |
|
|
Hi Tiago,
If I may comment on your post. While the following is my personal opinion and I am sure if you ask 3 people you will get 4 different opinions ;-) So far, I personally preferred the PDF-based version, since the html one has fairly long loading times and this is amplified due to the internal linking. - I also don't see a problem with the change in its look (but that's individual sensation). - Internal as well as external linking can be kept in the PDF-version as well. - Searching the file for keywords is also no problem. - Furthermore, with the PDF-version you are also constantly independent of an internet connection (yes, even nowadays this still counts as an argument, for some people) - Since you have it on GitHub anyway (and I guess you want to keep it up to date there as well) this could kind of replace the current html version. - Finally, you are the one who has most work with it and if option 2 semms to be one which is on the one hand the easiest for you and helps to keep the user guide up to date faster,.... why not? Hope, my and other opinions make your decision easier. best wishes, Jan -- ImageJ mailing list: http://imagej.nih.gov/ij/list.html |
|
In reply to this post by Tiago Ferreira-2
Hi Tiago,
> 2) Drop the current typesetting strategy, and use something else more > robust that can be automated without much fiddling. For what it's worth, the Open Microscopy Environment project achieves this goal using Sphinx: http://sphinx-doc.org/ E.g., for Bio-Formats 4.4.x: Source: https://github.com/openmicroscopy/bioformats/tree/dev_4_4/docs/sphinx HTML: https://www.openmicroscopy.org/site/support/bio-formats4/ PDF: https://www.openmicroscopy.org/site/support/bio-formats4/Bio-Formats-4.4.10.pdf It would be substantial effort to transform the ImageJ guide into Sphinx markup, but I think it would be much more maintainable afterward. Regards, Curtis On Sun, Feb 16, 2014 at 4:01 PM, 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 |
|
|
In reply to this post by Tiago Ferreira-2
Dear Tiago,
Thanks for all the work to keep the manual updated. Much appreciated! It is a very useful resource. Like Jan I prefer the pdf version of the manual. Looking at your dropbox version I seem not to be able to search for keywords within the text of the manual, only for keywords in the left side panel. Is this correct or do I miss something? Best wishes Kees Next imageJ workshops: http://www2.le.ac.uk/colleges/medbiopsych/facilities-and-services/cbs/lite/aif/workshops/imagej-workshops-14-and-15-April-2014 Dr Ir K.R. Straatman Senior Experimental Officer Centre for Core Biotechnology Services University of Leicester http://www2.le.ac.uk/colleges/medbiopsych/facilities-and-services/cbs/lite/aif -----Original Message----- From: ImageJ Interest Group [mailto:[hidden email]] On Behalf Of Tiago Ferreira Sent: 16 February 2014 22:02 To: [hidden email] Subject: Update and survey on the User Guide 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 |
Re: Update and survey on the User Guide
|
|
In reply to this post by Tiago Ferreira-2
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-Editor which 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/URI On 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 |
Re: Update and survey on the User Guide
|
|
Dear Tiago,
Personally, I prefer to use the HTML version because I find it easier to browse and search. However, I do like the "compromised" PDF-like version with the sidebar. It is easy enough to search via the browser. It would be good to be able to search the entire guide even when it is split into multiple files. For the URLs, the page-based scheme seems like a reasonable compromise. Both page numbers and section headings may change in the future, rendering the links inaccurate. However, pages will always be there, so an outdated link will at least not be broken. I'm an HTML newbie so there may be ways to create automatically up-to-date URLs that I am not aware of. Like many others, I thank you for creating a thorough and beautiful user guide. I use it myself, recommend it to my core facility users, and consider it a model for the kind of documentation I want to have for our facility instruments and software. Hope this helps, Theresa On Feb 17, 2014, at 11:59 AM, Jan Eglinger <[hidden email]> wrote: > 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-Editor > > which 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/URI > > On 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 > ------------------------------------ Theresa Swayne, Ph.D. Associate Research Scientist Manager, Confocal and Specialized Microscopy Shared Resource Herbert Irving Comprehensive Cancer Center, Columbia University 1130 Saint Nicholas Ave, 222A New York, NY 10032 212-851-4613 [hidden email] http://hiccc.columbia.edu/research/sharedresources/confocal -- ImageJ mailing list: http://imagej.nih.gov/ij/list.html |
|
In reply to this post by Tiago Ferreira-2
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 |
«
Return to ImageJ
|
1 view|%1 views
| Free forum by Nabble | Edit this page |