[ET Trac] [Einstein Toolkit] #1885: support bibtex in thorn documenation files

[Einstein Toolkit]

#1885: support bibtex in thorn documenation files
--------------------------+-------------------------------------------------
  Reporter:  rhaas        |       Owner:                     
      Type:  enhancement  |      Status:  review             
  Priority:  optional     |   Milestone:                     
 Component:  Cactus       |     Version:  development version
Resolution:               |    Keywords:                     
--------------------------+-------------------------------------------------

Comment (by rhaas):

 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.

-- 
Ticket URL: <https://trac.einsteintoolkit.org/ticket/1885#comment:7>
Einstein Toolkit <http://einsteintoolkit.org>
The Einstein Toolkit