support bibtex in thorn documenation files

Issue #1885 closed
Roland Haas created an issue

The pull request

https://bitbucket.org/cactuscode/cactus/pull-requests/new?source=rhaas/docs-bibtex&t=1

adds support for bibtex to Cactus' documentation system.

Keyword:

Comments (17)

  1. Erik Schnetter
    • removed comment

    How does this work? Where do the bibtex files go? Do they have to have specific names? Do you have an example where this is used (maybe in a different pull request)?

  2. Roland Haas reporter
    • removed comment

    The bibtex files go into the doc directories (usually, this is not really required). The code parses (as far as TeX is parsable by anything other than TeX) the code for bibliography commands then prepends the full path in front of each bibtex file listed (this is legal in LaTeX). The tricky piece is actually mixing thorns that use LaTeX's thebibliography with those that use bibliography. ThornGuide.pl collects all entries in thebibliography as before. It also outputs a single bibdata statement with all the collected bib files from all bibliography commands. The bibdata statement is the same as LaTeX's own bibliography command uses (see texmf/tex/latex/base/latex.ltx and search for \def\bibliography). Having the bibdata statements in the aux file is sufficient to run bibtex (which will generate lots of warnings about all the non-bibtex keys). The code the strips the extra \begin{thebibliography}, \end{thebibliography} lines from the beginning and end of the bibtex generated bbl file and includes the interior into the ThornGuide just after the collected thebibliography entries.

    There are already example thorns that use bibtex files (and failed before): * EinsteinAnalysis/AHFinderDirect * ExternalLibraries/MPI (this one is new and in a separate pull request)

  3. anonymous
    • removed comment

    I remember we had a discussion about it. Does anybody remember what the outcome was?

  4. Roland Haas reporter
    • removed comment

    I don't remember any outcome anymore. The changes has upsides of actually making it possible to use bibtext (which some thorns already do) and a downside of creating warnings if bibtex and non-bibtex bibs are mixed (not much I can do about this I think, trying to parse LaTeX is quite hard so I don't want to get fancy).

  5. Frank Löffler
    • removed comment

    Roland: could you please go over this again and see what the current status is? I would sound good to be able to use bibtex, of course. Can you provide an example of one of the warnings you talk about?

  6. Roland Haas reporter
    • removed comment

    The current status is that we have one thorn in the toolkit

    • EinsteinAnalysis/AHFinderDirect

    and a proposed change

    • ExternalLibraries/MPI

    that use .bib files in their documentation. Using bibtex in thorndocs is currently not supported (nor documented) in the ET. This means that at this point one can obtain a correct (ie no missing references) pdf file for the thorndoc of AHFinderDirect only if one runs pdflatex/bibtex/pdflatex/pdflatex manually on the tex file in AHFinderDirect/doc.

    The proposed patch (that worked fine at the time of the proposal) enables the use of bibtex in thorn docs. Bibtex entries can be freely mixed with manually added entries in the bibliography. However bibtex will produce a warning about "key not found" for every manually specified bibitem. The output however will be fine.

    The code works by producing some lower level LaTeX code that was copied from bibtex's actual output. This method will fail if someone write TeX code hard enough to parse that perl cannot match for the bilbiography command or if the content of the aux files changes (since the produce TeX code would be wrong). comment:3 provides a high level overview over what the code does.

    The important lines are https://bitbucket.org/cactuscode/cactus/pull-requests/new?source=rhaas/docs-bibtex&t=1#Llib/sbin/ThornGuide.plT270 and https://bitbucket.org/cactuscode/cactus/pull-requests/new?source=rhaas/docs-bibtex&t=1#Llib/sbin/ThornGuide.plT512 which collect bibliography commands and output them to the aux file.

  7. Roland Haas reporter
    • removed comment

    I did (the original proposer). I noticed that I had forgotten to sign in so it showed up as anonymous but could not figure out how to retroactively change the "closer".

    Are you saying you would actually champion this patch :-) Or just not sure who goes around closing tickets?

    It is being closed explicitly since there has been no review and it is not high enough on my list of priorities that I would be willing to fight for it (it also is a bit hackish since one has to know about LaTeX internals to make it work and parse .tex files in perl).

  8. Ian Hinder
    • removed comment

    The latter, obviously :)

    I am just a bit wary of the idea that valid tickets should be closed as "wontfix" just because nobody has addressed them yet. If you think the ticket addresses a legitimate issue, I would leave it open, perhaps with a low priority. Perhaps someone sees it and works on it. If you now think that this shouldn't be implemented, then close it as "wontfix". We have hundreds of open tickets; if we closed all of them due to inactivity, we would likely lose track permanently of some important things.

  9. Roland Haas reporter
    • removed comment

    I kind of agree. I was trying to keep the open tickets down so that searching for open tickets actually finds interesting ones. Also it means that our number of open tickets grows less quickly which is nice.

    I do think that the proposed patch is viable but given that no one commented on it, it seems not worthwhile to push for it unless someone else wants this feature as well (in which case they will have to search for it via the search button whether it is open or closed).

    I would rather then have people inspect patches that are more vital to me and the ET in general, definitely I do not want this patch to end up with a week long discussion :-)

  10. Zach Etienne
    • removed comment

    GiRaFFE documentation uses bibtex references and will not compile properly without them. In practice though, I only compile thorn documentation using

    pdflatex documentation.tex pdflatex documentation.tex pdflatex documentation.tex

    and adding the bibtex command to the mix is trivial.

  11. Log in to comment