* Thierry <sage-googlesu...@lma.metelu.net> [2016-09-21 18:35:25]:
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) ?
Et Voilà:
https://sphinxcontrib-bibtex.readthedocs.io/en/latest/
- 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.
--
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.
