Hi, bikeshedding for bikeshedding:
- if we decide to centralize everything in a single file (but we should be aware that a backward move (e.g. for modularization) will require some work), why not using bibtex (there must be some sphinx interface somewhere), to that we keep all information with proper fields (might also be good for pdf rendering) ? - regarding the citation link, explicit is better than implicit, avoids collisions, and is not that verbose: [Milnor1958], [AuthorCoauthor2016], ... My two cents, Thierry On Wed, Sep 21, 2016 at 08:46:29AM -0700, John H Palmieri wrote: > 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. -- 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.
