Using attribute values for references (tips)

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Using attribute values for references (tips)

DaLynxx
I was searching for ways to handle references in Asciidoc.

I found the "normal" anchor/link way i.e. [[ref]] and <<ref>> in the user manual however I needed to end up with IEEE styled references using numbers. i.e. [1][2] etc.

I found the asciidoc-bib, which is a sweet tool but I did not want to have to keep a separate bibTex file.

After reading some more I found that attributes could be used as a rather nice way of solving the problem.
In the beginning of the document I set attributes which I name to something easy to relate to e.g. <Author><Year>.
The values I assign is an ever increasing number. (hm... maybe its possible to nest the macros and use a counter?)
I also use the newly assigned attribute to create my list of references.
Then where ever I need to make a reference, I just use the {<attributename>} to get the number. See below for an example.
== References ==
{set:Mayer11:1} [{Mayer11}] Kim A. Mayer, "The Book", 2011 +
{set:Proctor12:2} [{Proctor12}] John S. Proctor, "My Story", 2012 +
{set:Stevens12:3} [{Stevens12}] Phil O. Stevens, "Things I Like", 2012

== Text ==
So here's a reference to [{Proctor12}], and then a reference to [{Stevens12}].

A nice thing is that you don't have to use numbers. You can assing letters A, B, C etc or anything else.
If you want to have your reference list in the end of the document, you still have to make the assignment early in the document, otherwise the attribute will not have a value when it reaches a reference and it will spell out the name instead of the assigned value.

Maybe it can be useful to someone else.

Tnx for a great tool!
Reply | Threaded
Open this post in threaded view
|

Re: Using attribute values for references (tips)

mojavelinux
Administrator
I understand that you want to customize the appearance of the bibliographic references in the output that Asciidoctor generates. While the solution you have proposed certainly works--perhaps suitable as a quick fix--I'd like to suggest another approach.

When working with AsciiDoc, we should keep a very important rule in mind. You should avoid doing output formatting in the AsciiDoc content, especially when that formatting steers you away from "normal" AsciiDoc syntax. Instead, you should put these types of customizations in a converter.

When you use a bibliography references, you are identifying the locations in the document where the references occur. The syntax of these markers do not restrict how the references appear in the output. Naturally, there is a default appearance for these references, which I understand does not conform to the IEEE style. The right approach here is to customize the output that is produced.

The easiest way to customize the output is to copy the applicable template files into a local template directory, modify them, and then reference that directory using the -T argument when you invoke asciidoctor. (I realize there is a lack of documentation about this procedure, though we are hoping to correct that soon).

Here is the templates you'll want to customize:


TIP: In place of "target", you would put a incremental number. It may be necessary to maintain a mapping between target names and target numbers.

Some trial and error is likely necessary. If you have questions, don't hesitate to ask!

Cheers,

-Dan


On Mon, Jun 23, 2014 at 10:42 AM, DaLynxx [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I was searching for ways to handle references in Asciidoc.

I found the "normal" anchor/link way i.e. [[ref]] and <<ref>> in the user manual however I needed to end up with IEEE styled references using numbers. i.e. [1][2] etc.

I found the asciidoc-bib, which is a sweet tool but I did not want to have to keep a separate bibTex file.

After reading some more I found that attributes could be used as a rather nice way of solving the problem.
In the beginning of the document I set attributes which I name to something easy to relate to e.g. <Author><Year>.
The values I assign is an ever increasing number. (hm... maybe its possible to nest the macros and use a counter?)
I also use the newly assigned attribute to create my list of references.
Then where ever I need to make a reference, I just use the {<attributename>} to get the number. See below for an example.
== References ==
{set:Mayer11:1} [{Mayer11}] Kim A. Mayer, "The Book", 2011 +
{set:Proctor12:2} [{Proctor12}] John S. Proctor, "My Story", 2012 +
{set:Stevens12:3} [{Stevens12}] Phil O. Stevens, "Things I Like", 2012

== Text ==
So here's a reference to [{Proctor12}], and then a reference to [{Stevens12}].

A nice thing is that you don't have to use numbers. You can assing letters A, B, C etc or anything else.
If you want to have your reference list in the end of the document, you still have to make the assignment early in the document, otherwise the attribute will not have a value when it reaches a reference and it will spell out the name instead of the assigned value.

Maybe it can be useful to someone else.

Tnx for a great tool!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Using-attribute-values-for-references-tips-tp1856.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: Using attribute values for references (tips)

DaLynxx
This post was updated on .
That escalated quickly...

I'm kind of lagging on both my slim as well as my ruby knowledge to really follow... we'll see if I manage to patch something up while trying to learn.
Your observation about having to generate a map between references and numbers is most likely necessary. Making 2 xreferences to the same bib entry should leave the same number, and since the engine will only
provide the text I assume you need to make some kind of look-up. One question though, wouldn't such mapping have to be done before parsing through the templates (is asciidoctor single or multi-pass parsing btw?). The template generated ruby statements tied to the bibliography will not be generated until later if the bibliography is at the end. For the wanted behaviour I need to know what number reference burgundy04 have been assigned when running into my inline :xref.

On a different but related note, while working through the files I ran into a behaviour of Asciidoctor I also would like to affect/challenge.

When working with large documents and long bibliographies you can easily end up referring to a non existent bib entry. Asciidoctor does not help me find those instances. I.e. the below non-existent bibliographic reference greg12 is accepted and generates the same type of links as the existing ones.

This might be wanted behaviour in terms of general x-references, but when making a bib ref you rather want to be able to search your document for some kind of error message e.g. [ERROR! Bib-ref, greg10, does not exist] so that the doc generator assists you in your work.

Maybe add a matching <<<bibxref>>> syntax to be able to differentiate behaviour between "normal" xrefs and bib-refs.

I have a bit still to go on my skills to be able to directly see if the error check could be implemented in the template as well (my guess is that it can but it kind of runs into the same problem as the one above, i.e. would need some pre-generated list to validate against in some || based assignment of either the ref text or an error message).
= Test

== References

Reference burgundy04 <<burgundy04>>

Reference mae02 <<mae02>>

Reference mac10 <<mac10>>

Reference non-exist <<greg12>>

[bibliography]
- [[[burgundy04]]] Burgundy, Ron, 2004
- [[[mac10]]] Mac, Freddie, 2010
- [[[mae02]]] Mae, Fannie, 2002

Update 1: Corrected an incomplete sentence.
Update 2: Several errors in my example
Update 3: corrected reference in text to be same as in example at end
Reply | Threaded
Open this post in threaded view
|

Re: Using attribute values for references (tips)

mojavelinux
Administrator
On Thu, Jul 3, 2014 at 10:30 AM, DaLynxx [via Asciidoctor :: Discussion] <[hidden email]> wrote:
That escalated quickly...

I'm trying to be better about keeping up with the list :)
 

Making 2 references to the same bib entry should leave the same number.

Agreed.
 
One question though, wouldn't such mapping have to be done before parsing through the templates (is asciidoctor single or multi-pass parsing btw?).

Asciidoctor parses in one step, converts (i.e., renders) in another. When the converter runs, Asciidoctor has access to the full document tree and all the information in it.

One caveat is that Asciidoctor does not perform inline parsing until the conversion phase. However, it does mine some inline data during parsing, including references. (You can see that here: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/parser.rb#L1198). It doesn't yet grab the bibliography references yet (https://github.com/asciidoctor/asciidoctor/issues/560) but we can fix that soon. In the meantime, you can use a preprocessor or treeprocessor to extract them before rendering.

 
The template generated ruby statements tied to the bibliography will not be generated until later if the bibliography is at the end. For the wanted behaviour I need to know what number burgundy10 have been assigned when running into my inline :xref.

That's totally possible.
 

On a different but related note, while working through the files I ran into a behaviour of Asciidoctor I also would like to affect/challenge.

When working with large documents and long bibliographies you can easily end up referring to a non existent bib entry. Asciidoctor does not help me find those instances. I.e. the below non-existent bibliographic reference greg12 is accepted and generates the same type of links as the existing ones.

This might be wanted behaviour in terms of general x-references, but when making a bib ref you rather want to be able to search your document for some kind of error message e.g. [ERROR! Bib-ref, greg10, does not exist] so that the doc generator assists you in your work.

Maybe add a matching <<<bibxref>>> syntax to be able to differentiate behaviour between "normal" xrefs and bib-refs.

I don't think another syntax is necessary since all references should have unique internal identifiers. We would just need to add the validation. That's currently not implemented for bibliography references, but it's entirely possible. I've added this enhancement to the issue referenced above (https://github.com/asciidoctor/asciidoctor/issues/560).

Cheers,

-Dan

--