[IPOL discuss] LaTeX publication & code documentation tool

[Nicolas Limare]

Hi Haldo,

> Together with Juan Cardelino we have been working in this publication. The
> idea of​this paper is to present some basic methods of edge detection in
> images.
> 
> This article is made entirely in Latex, so it could be interesting to test
> the Latex paper submission mechanism to IPOL.

I understand this as a "OK" to the proposition I sent you today about
this PDF submission. The (draft) author manual for this submission is
here:
  https://tools.ipol.im/wiki/ref/author_manual/

There probably are plenty of things to inprove in the process and its
documentation, your feedback is important for this improvement.

> Besides the paper, we have used a script to generate code documentation
> (which can be seen in Appendix 2 of the paper). This script and usage
> examples can be found in the Git repository:
> git://github.com/juan-cardelino/source_comment_extractor.git
> We think this tool may be useful for authors.

Yes. You may want to compare with literate programming tools, which
have a similar goal:
* lepton:
  http://www.fdpoisson.fr/cascimodot/doc/RRRR/R4-050412/lithiaote.pdf
* org-mode/babel:
  http://www.fdpoisson.fr/cascimodot/doc/RRRR/R4-050412/pouzat.pdf

> Here is the pdf version of the paper:
> http://iie.fing.edu.uy/~haldos/downloads/edge-detection-review-v5.pdf
> 
> It would be nice if someone could take a look of this and send some
> feedback.

Some short random comments:

* You detail the grayscale conversion in 7.1. Be careful, the PNG
  coefficients are not as reliable as I first thought they were. See
  the discussion on the PNG mailing-list:
  -> http://old.nabble.com/Re%3A-libpng-bug-tracker%3A-possible-rgb-to-gray-inaccuracies-td32166643.html
  You may also want to use rounding instead of truncation in the
  integer division, ie add 16384 before you divide by 32768

* If you detail the grayscale conversion, you should mention that is
  supposes an image in linear scale; do you handle the gamma correction
  in your code?

* Why do you use the MOV video format? This QuickTime format is
  Apple-centric, I think MPEG-4 or H.264, in an AVI container, are
  international ISO or ITU standard formats and better supported.

* All these videos, and the code, will be published and available on
  the article web page. This web page should be the only link you use
  to refer to any component of your article (manuscript, code, data,
  etc) becasue it is the only one we can maintain on the long term via
  the DOI handlers. So you should only link to this page. When you
  refer to the code or the video files, you should still refer to this
  page and add that the files are available from this page. No direct
  link to the article components, they are not maintainable.

* I recommend you not to include links in the PDF file like you would
  do in an HTML page. I mean no links like "download from here" in the
  "Source Code" paragraph, or the links in the "Video" section,
  because once the document is printed all this information is lost
  and the "from here" is meaningles. I recommend sentences like "from
  our web page", with the url clearly provided as a footnote. You can
  (and probably should) keep "our web page" and the URL clickable, for
  the best usability on a computer. 

> Finally, is the LaTeX publication process the same as before?

It is similar, not identical. I tried to document it in the (draft)
Author Manual (https://tools.ipol.im/wiki/ref/author_manual/). In
short:

* step 1: You upload a brief PDF file. An editor reads it, and if it
  looks like a real article adapted to IPOL you are allowed to proceed
  further.
* step 2: You upload a complete PDF file, with the code an all the
  supplementary material you want. You work with an IPOL editor to
  propose a web demo. Reviewers evaluate the article, ask for changes,
  and you go back to step 2 until the reviewers agree. Then the
  article is accepted.
* step 3: You upload the complete LaTeX source for your PDF file
  manuscript, we do some copyediting, fix typos, insert the final
  DOI, and everything is published online

Best,

-- 
Nicolas LIMARE - CMLA - ENS Cachan    http://www.cmla.ens-cachan.fr/~limare/
IPOL - image processing on line                          http://www.ipol.im/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://tools.ipol.im/mailman/archive/discuss/attachments/20120513/882e2af2/attachment.pgp>