Q: Generated per-doc bibliography from adoc bibliography master files?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Q: Generated per-doc bibliography from adoc bibliography master files?

wolandscat
Our technical documents refer to various publications and online resources in the normal way. Taken together, there are about 18 technical docs, probably 50 pages long on average (including diags etc); each might contain a dozen references.

These are done in the normal way using <<ref_id>> where in the references files there is a line like

. [[[ref_id]]] Author. Title. Year publisher [URL]

The question is how to manage these references properly. I have created 3 common files (but it could just be one) containing major groups of references; these files are included by the master.adoc root file of each of the specifications. The master bibliography files contain probably 50 - 60 items.

The result of just doing this is that each document, even if it contains only 5 external references ends up containing the whole of the master bibliography content.

The alternative would be to maintain document specific references files, but the problem is that many documents reference the same things, and we don't want them repeated in 18 separate files.

The kind of solution I would like is that Asciidoctor would compile a list of references in a source document it was processing, and then it when it got to [bibliography] sections, it would know to start including only those items for which references had been encountered. In this way, common master bibliography files could be maintained, but only the relevant content generated for each source document.

Has anyone considered anything like this with Asciidoctor?
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

mojavelinux
Administrator
Thomas,

You may want to check out asciidoc-bib, which helps manage bibliography references in AsciiDoc files (and includes Asciidoctor integration).


We've been talking about integrating this into Asciidoctor (perhaps simply by documenting it, or going deeper).


One of the hangups I have is that asciidoc-bib doesn't use the familiar <name>:<target>[<attributes>] syntax, so it feels inconsistent. But you can't argue with the benefits it brings.

I'd be interested to get your thoughts on asciidoc-bib. Is the the right direction for Asciidoctor? Should we do something different? I certainly recognize that citation / bibliography management is important and is therefore something on our roadmap.

Cheers,

-Dan

On Sun, Jul 19, 2015 at 4:23 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Our technical documents refer to various publications and online resources in the normal way. Taken together, there are about 18 technical docs, probably 50 pages long on average (including diags etc); each might contain a dozen references.

These are done in the normal way using <<ref_id>> where in the references files there is a line like

. [[[ref_id]]] Author. Title. Year publisher [URL]

The question is how to manage these references properly. I have created 3 common files (but it could just be one) containing major groups of references; these files are included by the master.adoc root file of each of the specifications. The master bibliography files contain probably 50 - 60 items.

The result of just doing this is that each document, even if it contains only 5 external references ends up containing the whole of the master bibliography content.

The alternative would be to maintain document specific references files, but the problem is that many documents reference the same things, and we don't want them repeated in 18 separate files.

The kind of solution I would like is that Asciidoctor would compile a list of references in a source document it was processing, and then it when it got to [bibliography] sections, it would know to start including only those items for which references had been encountered. In this way, common master bibliography files could be maintained, but only the relevant content generated for each source document.

Has anyone considered anything like this with Asciidoctor?


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Q-Generated-per-doc-bibliography-from-adoc-bibliography-master-files-tp3519.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

jvdh
In reply to this post by wolandscat
On Sun, 19 Jul 2015 12:23:04 +0200, wolandscat [via Asciidoctor ::  
Discussion] <[hidden email]> wrote:

>
>
> Our technical documents refer to various publications and online  
> resources in
> the normal way. Taken together, there are about 18 technical docs,  
> probably
> 50 pages long on average (including diags etc); each might contain a  
> dozen
> references.
>
> These are done in the normal way using <<ref_id>> where in the references
> files there is a line like
>
> . [[[ref_id]]] Author. Title. Year publisher [URL]
>
> The question is how to manage these references properly. I have created 3
> common files (but it could just be one) containing major groups of
> references; these files are included by the master.adoc root file of  
> each of
> the specifications. The master bibliography files contain probably 50 -  
> 60
> items.
>
> The result of just doing this is that each document, even if it contains
> only 5 external references ends up containing the whole of the master
> bibliography content.
>
> The alternative would be to maintain document specific references files,  
> but
> the problem is that many documents reference the same things, and we  
> don't
> want them repeated in 18 separate files.
>
> The kind of solution I would like is that Asciidoctor would compile a  
> list
> of references in a source document it was processing, and then it when it
> got to [bibliography] sections, it would know to start including only  
> those
> items for which references had been encountered. In this way, common  
> master
> bibliography files could be maintained, but only the relevant content
> generated for each source document.
>
> Has anyone considered anything like this with Asciidoctor?

I have encountered the same problem you describe. as long as asciidoc(tor)  
does not support this functionality out of the box I'm using the following  
solution:

* maintain the references in a bibtex database (".bib") file rather than  
in an asciidoc file

* scan asciidoc(tor) source with a dedicated script that locates all  
reference instances (`<<someref>>') and generates a fake latex aux-file  
(".aux") containing these references in latex-compatible format. so this  
aux-file looks like as if it where generated by `latex' itself after  
processing a tex-file containing those references.

* the script than calls `bibtex' on the `.aux' file which generates a  
".bbl" file containing only the references actually used in `latex' syntax.

* the script than converts the `.bbl' file into the actual asciidoc  
references file (I use an extension `.ref') containing the `[[someref]]]'  
stuff by a chain of regex substitutions (not fail-safe but good enough if  
one considers only a couple of bibtex styles for
formatting the references)

* the document than just `::include's the auto-generated .ref file.

this works fine, provided you have a latex installation and know how to  
adjust the formatting/style of the bibliography by using a suitable bibtex  
style file.

it would of course be possible to do the same without involving bibtex  
(but the advantage of using the latter is, of course, that one can switch  
between styles for different formatting requirements of the references  
easily) by making the script itself perform a lookup of the actually used  
references in a (asciidoc) reference-file and extracting them to a  
tmp-file (".ref") which is included in the document.

>
> _______________________________________________
> If you reply to this email, your message will be added to the discussion  
> below:
> http://discuss.asciidoctor.org/Q-Generated-per-doc-bibliography-from-adoc-bibliography-master-files-tp3519.html
>
> To unsubscribe from Asciidoctor :: Discussion, visit  
>
Using Opera's revolutionary email client:
http://www.opera.com/mail/
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

wolandscat
In reply to this post by mojavelinux
Thanks for the pointer - I'll try to get it working in some form this week.
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

wolandscat
In reply to this post by jvdh
Thanks for the info.

I suspect we won't literally use this solution because we are not latex-oriented (one must occasionally try to keep the tool-count down ;-) but your general design will probably be able to teach us something - I may have questions when I get the basic asciidoc-bib thing running.

(right now messing with antlr4 source highlighting in Pygments - converting all our grammars from old style yacc bnf is taking time...)
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

jxxcarlson
I would certainly used something along these lines (a master bibliography file
of which only the references cited are incorporated in the document).  Three cheers!
Reply | Threaded
Open this post in threaded view
|

Re: Q: Generated per-doc bibliography from adoc bibliography master files?

rhtse
I just came across this thread and if you're still trying to do citing inside AsciiDocs, we've just created an alternative called `asciidoctor-bibliography' .

The gem fully bridges CSL styles and supports all TeX-style citation formats. Please feel free to provide any feedback if you encounter any issues. Thanks!