COIN-OR::LEMON - Graph Library

Opened 11 years ago

Closed 10 years ago

#184 closed task (done)

Bibliography for LEMON

Reported by: Peter Kovacs Owned by: Peter Kovacs
Priority: major Milestone: LEMON 1.2 release
Component: documentation Version:
Keywords: Cc:
Revision id:

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

Attachments (16)

bibtex2dox.py (24.9 KB) - added by Peter Kovacs 10 years ago.
references.bib (7.8 KB) - added by Peter Kovacs 10 years ago.
bibtex2dox-table.py (25.1 KB) - added by Peter Kovacs 10 years ago.
references.2.bib (9.6 KB) - added by Peter Kovacs 10 years ago.
Reformatted with emacs
848db1b1cec6.patch (39.0 KB) - added by Alpar Juttner 10 years ago.
references.3.bib (9.7 KB) - added by Peter Kovacs 10 years ago.
bibtex.bundle (11.0 KB) - added by Alpar Juttner 10 years ago.
184-f92258d6ea47.patch (2.6 KB) - added by Peter Kovacs 10 years ago.
184-1-420e33e37120.patch (4.5 KB) - added by Peter Kovacs 10 years ago.
184-2-1de05cf355c5.patch (13.3 KB) - added by Peter Kovacs 10 years ago.
184-3-a1411abaf71d.patch (1.2 KB) - added by Peter Kovacs 10 years ago.
184-reworked-2de0fc630899-134852d7fb0a-53bea38f71cb.bundle (4.2 KB) - added by Peter Kovacs 10 years ago.
184-lemon-header-f1d3044d4a5a.patch (1.1 KB) - added by Peter Kovacs 10 years ago.
184-header1-e3ef3a03fe5a.patch (518 bytes) - added by Peter Kovacs 10 years ago.
184-header2-c06eacc1f28e.patch (1.1 KB) - added by Peter Kovacs 10 years ago.
184-header-latest-c841ae1aca29.patch (973 bytes) - added by Peter Kovacs 10 years ago.

Download all attachments as: .zip

Change History (55)

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 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 ; 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 ; Changed 10 years ago by 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?

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

comment:9 in reply to:  6 Changed 10 years ago by 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.

comment:10 in reply to:  7 ; Changed 10 years ago by 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.)

comment:11 in reply to:  8 Changed 10 years ago by 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).

comment:12 in reply to:  10 ; Changed 10 years ago by 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.

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

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

Replying to kpeter:

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

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!

Changed 10 years ago by Peter Kovacs

Attachment: bibtex2dox.py added

Changed 10 years ago by Peter Kovacs

Attachment: references.bib added

Changed 10 years ago by Peter Kovacs

Attachment: bibtex2dox-table.py added

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

Attachment: references.2.bib added

Reformatted with emacs

comment:18 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

Replying to alpar:

Looks good. Shall we incorporate it to the repo?

Let's do it.

comment:20 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?

Changed 10 years ago by Alpar Juttner

Attachment: 848db1b1cec6.patch added

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.
  • Add copyright notice to the script.
  • Use the references in the doc

Changed 10 years ago by Peter Kovacs

Attachment: references.3.bib added

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

Replying to alpar:

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

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

Changed 10 years ago by Alpar Juttner

Attachment: bibtex.bundle added

comment:23 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.

Changed 10 years ago by Peter Kovacs

Attachment: 184-f92258d6ea47.patch added

comment:24 in reply to:  23 ; Changed 10 years ago by 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?

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

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.

Changed 10 years ago by Peter Kovacs

Attachment: 184-1-420e33e37120.patch added

Changed 10 years ago by Peter Kovacs

Attachment: 184-2-1de05cf355c5.patch added

Changed 10 years ago by Peter Kovacs

Attachment: 184-3-a1411abaf71d.patch added

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

comment:28 Changed 10 years ago by Peter Kovacs

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

comment:29 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
Status: assignedclosed

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.

comment:31 Changed 10 years ago by Peter Kovacs

Resolution: done
Status: closedreopened

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.

Changed 10 years ago by Peter Kovacs

comment:32 in reply to:  31 ; Changed 10 years ago by 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 

comment:33 in reply to:  32 Changed 10 years ago by 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?

Changed 10 years ago by Peter Kovacs

Changed 10 years ago by Peter Kovacs

comment:34 Changed 10 years ago by Peter Kovacs

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

comment:35 in reply to:  34 ; Changed 10 years ago by 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.

comment:36 in reply to:  35 ; Changed 10 years ago by 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?

comment:37 in reply to:  36 ; Changed 10 years ago by 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.

comment:38 in reply to:  37 ; Changed 10 years ago by 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.

Changed 10 years ago by Peter Kovacs

comment:39 in reply to:  38 Changed 10 years ago by Alpar Juttner

Resolution: done
Status: reopenedclosed

Replying to kpeter:

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

Thanks. It is in the main branch now.

Note: See TracTickets for help on using tickets.