Opened 11 years ago

Closed 9 years ago

# Bibliography for LEMON

Reported by: Owned by: Peter Kovacs Peter Kovacs major LEMON 1.2 release documentation

### Description

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):

### comment:1 Changed 11 years ago by Alpar Juttner

Owner: changed from Alpar Juttner to Peter Kovacs

### comment:2 Changed 11 years ago by Peter Kovacs

Milestone: LEMON 1.1 release

### comment:4 follow-up:  5 Changed 10 years ago by Alpar Juttner

Milestone: → LEMON 1.2 release

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?

### comment:5 in reply to:  4 ; follow-up:  6 Changed 10 years ago by 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.

### comment:6 in reply to:  5 ; follow-up:  9 Changed 10 years ago by Peter Kovacs

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?

### comment:7 follow-up:  10 Changed 10 years ago by 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).

### comment:8 follow-up:  11 Changed 10 years ago by Peter Kovacs

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

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

### comment:9 in reply to:  6 Changed 10 years ago by Alpar Juttner

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

### comment:10 in reply to:  7 ; follow-up:  12 Changed 10 years ago by Alpar Juttner

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.)

### comment:11 in reply to:  8 Changed 10 years ago by Alpar Juttner

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).

### comment:12 in reply to:  10 ; follow-up:  14 Changed 10 years ago by Peter Kovacs

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.

### comment:13 follow-up:  15 Changed 10 years ago by Peter Kovacs

What about a solution that depends on bibtex, just like

or on bison, like

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

### comment:14 in reply to:  12 ; follow-up:  16 Changed 10 years ago by Alpar Juttner

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.

### comment:15 in reply to:  13 Changed 10 years ago by Alpar Juttner

What about a solution that depends on bibtex, just like

or on bison, like

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

### comment:16 in reply to:  14 Changed 10 years ago by Peter Kovacs

Status: new → assigned

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!

### comment:17 Changed 10 years ago by Peter Kovacs

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

### Changed 10 years ago by Peter Kovacs

Reformatted with emacs

### comment:18 follow-up:  19 Changed 10 years ago by Alpar Juttner

Looks good. Shall we incorporate it to the repo?

### comment:19 in reply to:  18 Changed 10 years ago by Peter Kovacs

Looks good. Shall we incorporate it to the repo?

Let's do it.

### comment:20 follow-up:  22 Changed 10 years ago by 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?

### comment:21 Changed 10 years ago by 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.
• Use the references in the doc

### comment:22 in reply to:  20 Changed 10 years ago by Peter Kovacs

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

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

### comment:23 follow-up:  24 Changed 10 years ago by 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.

### comment:24 in reply to:  23 ; follow-up:  25 Changed 10 years ago by Peter Kovacs

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?

### comment:25 in reply to:  24 Changed 10 years ago by 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.

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!

### comment:26 Changed 10 years ago by 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.

### comment:27 Changed 10 years ago by 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.
• 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.

### comment:29 follow-up:  30 Changed 10 years ago by 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].

### comment:30 in reply to:  29 Changed 10 years ago by Alpar Juttner

Resolution: → done assigned → closed

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.

### comment:31 follow-up:  32 Changed 10 years ago by Peter Kovacs

Resolution: done closed → reopened

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.

### comment:32 in reply to:  31 ; follow-up:  33 Changed 10 years ago by Alpar Juttner

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


### comment:33 in reply to:  32 Changed 10 years ago by Peter Kovacs

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?

### comment:34 follow-up:  35 Changed 10 years ago by Peter Kovacs

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

### comment:35 in reply to:  34 ; follow-up:  36 Changed 9 years ago by Alpar Juttner

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.

### comment:36 in reply to:  35 ; follow-up:  37 Changed 9 years ago by Peter Kovacs

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?

### comment:37 in reply to:  36 ; follow-up:  38 Changed 9 years ago by Alpar Juttner

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

I've no preference.

### comment:38 in reply to:  37 ; follow-up:  39 Changed 9 years ago by Peter Kovacs

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.