Bibliography for LEMON

[Peter Kovacs]

It would be useful if we have references (books, articles etc.) for the algorithm and data structure implementations and other parts of the library. Especially if we also target scientists.

The main question is how to add bibliography to the doxygen documentation, e.g. from a bibtex file.

Several solutions exists for this purpose, we should check them, decide which one to use and add it to the build system.

This question arose in #176. Alpar wrote there:

... bibtex2html is not really a ubiquitous tools, maybe because it is written in the somewhat exotic !OCaml language. We may also want to have a look at these (in the future):

• ​http://people.csail.mit.edu/rahimi/bibtex/
• ​http://www.irisa.fr/lagadic/soft/bib2html/bib2html.html
• ​http://www.authopilot.com/xml/home.htm

[Alpar Juttner]

Some other useful links.

• ​http://www.dmoz.org/Computers/Software/Typesetting/TeX/BibTeX/

Collection of links

• ​http://ralyx.inrialpes.fr/2008/Raweb/artis/uid41.html

BibTeX processing library written in C++

• ​http://www.litech.org/~wkiri/bib2html/

Command line utility

• ​http://www.cis.udel.edu/~sprenkle/bibtex2html/

Python stuff

[Alpar Juttner]

I strictly would like to avoid additional dependencies, so, I'm looking for a bib->html converter (bib->dox would be even better!) which source could be embedded into the LEMON repo. The best would be something in C/C++, but I couldn't find anything reasonable on the web.

However, I found ​this one, which is a promising bib->xml converter written in Python. Could anyone have a look at it and check if it is possible to hack a bib->dox converter based on it?

[Alpar Juttner]

However, I found ​this one, which is a promising bib->xml converter written in Python. Could anyone have a look at it and check if it is possible to hack a bib->dox converter based on it?

Alternatively, we might use this script as is, and write a small python script that translate its XML output into .dox format. This should be fairly easy to do.

[Peter Kovacs]

Replying to alpar:

Alternatively, we might use this script as is, and write a small python script that translate its XML output into .dox format. This should be fairly easy to do.

I think modifying the original script to produce .dox output instead of .xml would also be easy. What about the license? Does it make this solution also possible?

[Peter Kovacs]

I tried to modify the script, so I examined it. It is very simple, hardly does more than transforming xyz = {abc} like patterns to <bibxml:xyz>abc</bibxml:xyz>. So the most important tasks are not solved in this script (the order and the formatting of the different parts of an entry).

[Peter Kovacs]

This script can be combined with such conversions, as you can find here:

​http://www.cis.udel.edu/~sprenkle/bibtex2html/

But it needs an XSLT implementation, such as xt, as far as I understand.

[Alpar Juttner]

Replying to kpeter:

What about the license? Does it make this solution also possible?

I think yes. As far as I remember, it is GPLv2 or something like that. It should be at the beginning of the file.

[Alpar Juttner]

Replying to kpeter:

So the most important tasks are not solved in this script (the order and the formatting of the different parts of an entry).

You are right. That's exactly why I suggested the second approach. Parsing XML is trivial with python (e.g. with the xml.dom.minidom module.)

[Alpar Juttner]

Replying to kpeter:

But it needs an XSLT implementation, such as xt, as far as I understand.

Yes, you again rightly unveil the reasons behind my suggestion - I would like to avoid this dependence. Moreover it might be better to use the .dox format instead of HTML. (My feeling is that the cross linking will be better if we use Doxygen's internal linking mechanism).

[Peter Kovacs]

Replying to alpar:

You are right. That's exactly why I suggested the second approach. Parsing XML is trivial with python (e.g. with the xml.dom.minidom module.)

I see. But I think determining the correct order and formatting of the various fields of different bibtex entries is the most difficult part of the whole task. That's why I would like to use such a tool, that solves this issue.

[Peter Kovacs]

What about a solution that depends on bibtex, just like

• ​http://people.csail.mit.edu/rahimi/bibtex/

or on bison, like

• ​http://www.litech.org/~wkiri/bib2html/

These dependences are also unwanted? (These tools are usually present on a unix-like system, aren't they?)

[Alpar Juttner]

Replying to kpeter:

I see. But I think determining the correct order and formatting of the various fields of different bibtex entries is the most difficult part of the whole task.

Why is that so difficult? For example, order in the fist round can be just authors, title, journal or conf place and date. We can simply write a formatting function for each basic enty type (@article, @inproceedings, @book), then we can extend it later when new entry types or new fields appear.

[Alpar Juttner]

Replying to kpeter:

What about a solution that depends on bibtex, just like

• ​http://people.csail.mit.edu/rahimi/bibtex/

or on bison, like

• ​http://www.litech.org/~wkiri/bib2html/

Did you have a try with them? I ranked them non-starters after a short look. Tell us if you have better experiences.

[Peter Kovacs]

Replying to alpar:

Why is that so difficult? For example, order in the fist round can be just authors, title, journal or conf place and date. We can simply write a formatting function for each basic enty type (@article, @inproceedings, @book), then we can extend it later when new entry types or new fields appear.

Okay, neither it is so diffcult, nor it is so easy. I just wanted to avoid implementing the special formattings, correct sorting etc., but finally I tried to implement all features that I think we need.

I attached the modified python script, along with a preliminary collection of references. You can try the script applying to this bibtex file. I did not modify the header of the script (copyright and license information), thus this part should be extended and slightly modified if the script will be accepted to involve in the LEMON repository.

Feel free to improve the script!

[Peter Kovacs]

bibtex2dox-table.py is a sligthly modified version that uses html tables in the generated doxygen output to arrange the entries.

[Peter Kovacs]

Reformatted with emacs

[Alpar Juttner]

Looks good. Shall we incorporate it to the repo?

[Peter Kovacs]

Replying to alpar:

Looks good. Shall we incorporate it to the repo?

Let's do it.

[Alpar Juttner]

1. AFAIK, bibtex allows an URL= field, too. Can't we use this instead of

   howpublished = "\url{...}"
   

2. Why both " and { are used in the fields in references.2.bib​?

[Alpar Juttner]

[848db1b1cec6] integrates the bibtex to .dox converter into repo.

Akos, could you please have a look at the autoconf/cmake files and check/test if they work properly on all supported platforms? (E.g. is it OK to use / as directory separator in windows?)

More things to do

• Fix the issues in comment 20 if need be.
• Add copyright notice to the script.
• Use the references in the doc

[Peter Kovacs]

Replying to alpar:

2. Why both " and { are used in the fields in references.2.bib​?

Now only {} is used, see references.3.bib​.

[Alpar Juttner]

The attached bibtex.bundle​ contains the integration of this bibtex to dox converter into both build environment.

It is still a question how to actually use the references, i.e. how to cite them from the doc.

[Peter Kovacs]

Replying to alpar:

The attached bibtex.bundle​ contains the integration of this bibtex to dox converter into both build environment.

It is still a question how to actually use the references, i.e. how to cite them from the doc.

I tried to solve this question in [f92258d6ea47] using \section command for each bibtex entry. It has the great advantage that the bibtex ids can be used throughout the doc with \ref. However doxygen sections cannot be wraped into any kind of html tags, thus I used a somewhat ugly solution for formatting the output, but the result seems to be acceptable. What do you think?

I also modified Makefile.am, since your version does not work with automake 1.9.6. Could you verify that this version is accepted by your newer automake as well?

[Alpar Juttner]

Replying to kpeter:

Replying to alpar:

The attached bibtex.bundle​ contains the integration of this bibtex to dox converter into both build environment.

It is still a question how to actually use the references, i.e. how to cite them from the doc.

I tried to solve this question in [f92258d6ea47] using \section command for each bibtex entry. It has the great advantage that the bibtex ids can be used throughout the doc with \ref. However doxygen sections cannot be wraped into any kind of html tags, thus I used a somewhat ugly solution for formatting the output, but the result seems to be acceptable. What do you think?

Excellent!

[Alpar Juttner]

I pushed there changes into the main branch as [94ef0a5c0005],[f8c468367dab] and [68792fb2870f]

Now, one can cite references from the file doc/references.bib with the usual

\ref label

command, where label is the one that are given in the .bib file.

I still leave the ticket open for the patches actually inserting citations into the doc.

[Peter Kovacs]

I attached three changesets:

• [420e33e37120] improves the script to handle url fields and uses them in the bibtex file.
• [1de05cf355c5] inserts citations into the doc.
  • Add general citations to modules.
  • Add specific citations for max flow and min cost flow algorithms.
  • Add citations for the supported LP and MIP solvers.
  • Extend the main page.
  • Replace inproceedings entries with the journal versions.
  • Add a new entry about network simplex.
  • Remove uncited (and potentially unwanted) entries.
• [a1411abaf71d] is not a strictly related changeset, it just updates the doxygen config file to avoid a warning about deprecated option.

Please check the changes of [1de05cf355c5], especially on the main page.

[Peter Kovacs]

I think there is only one task left here: add copyright notice to the script. Alpar, could you please do it?

[Peter Kovacs]

The attached bundle contains the reworked versions of the former patches, in which the references to Boost, LEDA and the self-reference to the LEMON itself are not removed. The new changesets are [2de0fc630899], [134852d7fb0a], [53bea38f71cb].

[Alpar Juttner]

Replying to kpeter:

The attached bundle contains the reworked versions of the former patches, in which the references to Boost, LEDA and the self-reference to the LEMON itself are not removed. The new changesets are [2de0fc630899], [134852d7fb0a], [53bea38f71cb].

They all are in the main branch now.

[Peter Kovacs]

I attached a patch [f1d3044d4a5a] that adds the same header to bib2dox.py as in chg-len.py.

Note that the first line of these scripts were also different and I'm not sure which one is better, thus I used the one from chg-len.py.

[Alpar Juttner]

Replying to kpeter:

I attached a patch [f1d3044d4a5a] that adds the same header to bib2dox.py as in chg-len.py.

The problem is that the script is based on a third party code and - at least for me - it is unclear whether it is appropriate to use our default copyright header in this case. That's why I didn't add extra copyright notices just a note that the script is a modification of the original authors' code.

Note that the first line of these scripts were also different and I'm not sure which one is better, thus I used the one from chg-len.py.

You are right, it should be

#! /usr/bin/env python 

[Peter Kovacs]

Replying to alpar:

The problem is that the script is based on a third party code and - at least for me - it is unclear whether it is appropriate to use our default copyright header in this case. That's why I didn't add extra copyright notices just a note that the script is a modification of the original authors' code.

I see. What to do then?

[Peter Kovacs]

I attached two alternative solutions: [e3ef3a03fe5a] and [c06eacc1f28e].

[Alpar Juttner]

Replying to kpeter:

I attached two alternative solutions: [e3ef3a03fe5a] and [c06eacc1f28e].

If I remember correctly, using a pair of """s is the preferred way of documenting a Python code. Probably because it integrates better with Python's help system.

[Peter Kovacs]

Replying to alpar:

If I remember correctly, using a pair of """s is the preferred way of documenting a Python code. Probably because it integrates better with Python's help system.

Okay, let's us that form. Apart from that, which header do you find the best?

[Alpar Juttner]

Replying to kpeter:

Okay, let's us that form. Apart from that, which header do you find the best?

I've no preference.

[Peter Kovacs]

Replying to alpar:

Replying to kpeter:

Okay, let's us that form. Apart from that, which header do you find the best?

I've no preference.

The attached patch [c841ae1aca29] seems to be an acceptable solution.

[Alpar Juttner]

Replying to kpeter:

The attached patch [c841ae1aca29] seems to be an acceptable solution.

Thanks. It is in the main branch now.