Re: [Boost-docs] How best to handle references using Quickbook

Subject: Re: [Boost-docs] How best to handle references using Quickbook
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2011-10-21 15:43:13

Le 21/10/11 13:41, Paul A. Bristow a écrit :
> I'm revisiting some docs that involve lots of references.
>
> I'm using Quickbook footnotes, (putting the reference at the bottom m of the page, but I'd *also*
> like a full list of references in a section References.
>
> So I'm using Quickbook footnotes with macros.
>
> [def __Coplien James O. Coplien. Advanced C++ Programming Styles and Idioms. Addison Wesley, Reading
> Massachusetts, 1992.]
>
> calling thus
>
>     ... flexible numerical software architecture [footnote __Coplien], [footnote __MISRA]
>     ...
> What this *doesn't* allow one to do is to find where the reference is used in the original text.
I guess that this a good candidate for a new quickbook feature ;-)
> (And it's bit tiresome creating the macros :-(
I find the use of your macros quite succinct and clear. I think I will 
adopt it in my documents.
> Any suggestions on how to do this better?
>
Sorry, but I don't see one without updating the quickbook language. If 
we added a reference into the language

References

[reference:Coplien James O. Coplien. Advanced C++ Programming Styles and Idioms. Addison Wesley, Reading
Massachusetts, 1992.]
[reference:MISRA  MISRA. MISRA-C++ 2008: Guidelines for the Use of the C++ Language in Critical Systems. MISRA
Consortium, MISRA-C++, 2008.]

and a footnote-reference, then we could use them as

... flexible numerical software architecture [footnote-reference Coplien], [footnote-reference MISRA]

In this way any external reference could be referenced from the documentation. What is the added value of this approach? Not too much other than setting the infrastructure to provide the missing feature.

Best,
Vicente

Best,
Vicente