Docutils: Documentation Utilities

On Sat, 29 Jul 2006, martin f krafft apparently wrote: 
> I am considering getting rid of latex once and for all and using RST 
> instead to write my thesis, thinking that I can do pretty much all 
> I want with it. 
> However, the one thing lacking is still citations.

They are not 'lacking' but rather citation handling
is inadequate to scholarly work.  If you look at the
archives you will find much discussion of this,
some very recent.

> Docutils seems to support citations [0], but when I run 
> rst2latex or rst2newlatex, I note that these are in no way 
> compatible with BibTeX, but instead just a sort of 
> footnote (as the documentation states).  Have you 
> considered allowing syntax like [Krafft:2005:DSCT]_ to be 
> turned into \cite{Krafft:2005:DSCT} by the LaTeX writer, 

This has been suggested several times.  I hope that it
will be supported as an option for the LaTeX writer.
(I have not checked recently that it is not.)


> Or even better, make RST work with BibTeX, so that even 
> HTML output gets a proper bibliography? 

If you just want a sorted list of reST style citations,
I have developed a BibStuff solution for this (essentially
an enhancement of addrefs.py).  It scans an reST document
for citation references, used the labels as keys for your
.bib database, sorts and formats the matches in the
database, and outputs them as reST citations (which you
can 'include' in your document).  Write me offlist if
you want to test it.  Or wait a couple weeks, and it
will be part of BibStuff.

Cheers,
Alan Isaac

also sprach Alan G Isaac <aisaac@...> [2006.07.29.1821 +0100]:
> They are not 'lacking' but rather citation handling
> is inadequate to scholarly work.  If you look at the
> archives you will find much discussion of this,
> some very recent.

I did look. really. A search for bibtex and docutils or rst gives
nothing though.

--=20
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@...
=20
spamtraps: madduck.bogus@...
=20
"once ... in the wilds of afghanistan, i lost my corkscrew, and we
 were forced to live on nothing but food and water for days."
                                -- w. c. fields, "my little chickadee"

At http://news.gmane.org/gmane.text.docutils.user look for
the "citation enhancement" thread.

Cheers,
Alan Isaac

[martin f krafft]

>I am considering getting rid of latex once and for all and using RST
>instead to write my thesis, thinking that I can do pretty much all
>I want with it.
>However, the one thing lacking is still citations. [...]

May you go without any references, to various pages from within your=20
text, in your printed document?  And don't you need some machinery for=20
building various alphabetical indexes at the end?

--=20
Fran=E7ois Pinard   http://pinard.progiciels-bpi.ca

also sprach Fran=E7ois Pinard <pinard@...> [2006.07.29.2032 +0=
100]:
> May you go without any references, to various pages from within your=20
> text, in your printed document?  And don't you need some machinery for=20
> building various alphabetical indexes at the end?

Well, I don't understand the first part (do you mean section
references?), but the index is something I'll have to think about.

--=20
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@...
=20
spamtraps: madduck.bogus@...
=20
"if i am occasionally a little overdressed, i make up for it by being
 always immensely over-educated."
                                                        -- oscar wilde

[martin f krafft]

>Well, I don't understand the first part (do you mean section
>references?),

Most probably, yes.  The final document has to be printed and=20
self-contained, isn't it?  I presume you intend to rely on the Docutils=20
LaTeX writer, instead of directly writing LaTeX?  I've not much=20
experience with the LaTeX writer, but I'm tempted to guess it would do=20
well with section references.   The truth is that I tried the LaTeX=20
writer a few times in the past, but each time, it was more or less of=20
a fight for me.  Since then, I read that it has been much refactored:
so I should ideally find an opportunity for retrying a modern version.

>the index is something I'll have to think about.

Make sure to share your finding with the group, or at least with me! :-)
I'd have good use for indices, if they were available somehow within=20
reST.  I did some stunts and kludges to get them in the past, but=20
nothing neat.

--=20
Fran=E7ois Pinard   http://pinard.progiciels-bpi.ca

On Sat, Jul 29, 2006, Fran?ois Pinard wrote:
> 
> And don't you need some machinery for 
> building various alphabetical indexes at the end?

There's code in my sandbox for that.  It's extremely badly out of date,
but probably still of some use.
-- 
Aahz (aahz@...)           <*>         http://www.pythoncraft.com/

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are, by
definition, not smart enough to debug it."  --Brian W. Kernighan

On Sat, 29 Jul 2006, Alan G Isaac wrote:

> On Sat, 29 Jul 2006, martin f krafft apparently wrote:
>> I am considering getting rid of latex once and for all and using RST
>> instead to write my thesis, thinking that I can do pretty much all
>> I want with it.
>> However, the one thing lacking is still citations.
>
> They are not 'lacking' but rather citation handling
> is inadequate to scholarly work.  If you look at the
> archives you will find much discussion of this,
> some very recent.
>
>> Docutils seems to support citations [0], but when I run
>> rst2latex or rst2newlatex, I note that these are in no way
>> compatible with BibTeX, but instead just a sort of
>> footnote (as the documentation states).  Have you
>> considered allowing syntax like [Krafft:2005:DSCT]_ to be
>> turned into \cite{Krafft:2005:DSCT} by the LaTeX writer,
>
> This has been suggested several times.  I hope that it
> will be supported as an option for the LaTeX writer.
> (I have not checked recently that it is not.)

it would be much easier for me if i get an example of input and the 
expected output, this might even find into the test set of docutils,
"it does not work" is unlikely to get fixed.

i am talking of rst2latex not rst2newlatex, that would be felix
and a new syntax like "[..]" is care of dgoodger of course

cheers

also sprach grubert@... <grubert@...> [=
2006.07.31.1033 +0100]:
> it would be much easier for me if i get an example of input and the=20
> expected output, this might even find into the test set of docutils,
> "it does not work" is unlikely to get fixed.

I understand, but there are many paths to do, so which one do we go?
Do we generate a .aux file and use bibtex, then parse the output and
turn it into rst? That's a hack! Or should we see where
python-bibtex can take us and go from there? I think that's the
better way to do it for all but the latex output format. In that
case, we should really just let latex/bibtex work together.

FWIW, here's an example BibTeX entry:

@BOOK{Krafft:2005:DSCT,
  title =3D {The Debian System --- Concepts and Techniques},
  publisher =3D {Open Source Press},
  year =3D {2005},
  author =3D {Martin F. Krafft},
  address =3D {Munich, Germany},
  month =3D {June},
  owner =3D {madduck},
  timestamp =3D {2006.07.27},
  url =3D {http://debiansystem.info}
}

Now, in terms of the syntax to use in the text, [Krafft:2005:DSCT]_
would be good, but it's taken already. Could we do something like
(Krafft:2005:DSCT)_, or is this too close? or {} ?

Note that the colons need not appear in the identifier, that's just
the format I follow.

--=20
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@...
=20
spamtraps: madduck.bogus@...
=20
it's as bad as you think, and they are out to get you.