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 behavior). 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.) -- John -- 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 sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
