There may be two issues here.

- How should references be written in source code?
- How should references appear in documentation output?

The default behavior in Sphinx is to use the source code citation name also 
in the output. I don't know how hard it would be to change that.

We can have discussions about the best way to format references purely in 
the documentation output, and I think it is clear that we will not come to 
universal agreement. More importantly, any discussion strictly about the 
documentation output (for example, using [1], [2], ... -- no one is 
suggesting that this is how the references should be named in the source 
code, right?) is orthogonal to the issue at hand: anyone can work on 
modifying Sphinx so it formats the references in another way independently 
of the format in the source code. Feel free to do that and propose such a 
change here. For now, the discussion should be on how to format code in the 
source (= the format in the output for now, because that is Sphinx's 

So we can discuss the best way to format references in the source code. To 
some extent, of course, this is bikeshedding. Whether we use [AC2016] or 
[MR234898349] or [doi:...] or something else, there will always be 
arguments for doing one of the others. I personally find [Mil1958] in a 
discussion of the Steenrod algebra to convey information: I know that it 
refers to Milnor's 1958 paper. I would not recognize the MR number or the 
doi number for this. So I personally find the format [AC2016] a good 
balance between readability, brevity, and (to a large extent) unique 
representation. (Also, my suggested usage would be to often include more 
information than just the citation name: "In [Mil1958], Milnor showed ..." 
or "Milnor showed that ... -- see [Mil1958]" or something similar. Again, 
there is a balance between readability and verbosity.)


You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
To post to this group, send email to
Visit this group at
For more options, visit

Reply via email to