In any large document, such as the sage manuals, there are bound to be uniqueness issues with the choice of labels for references. The best way to resolve this is for us to start using a specified format for the references. Currently we do not even have guidelines for this so it is not surprising that different people do different things.
It would also help to have the references appearing in one file, as William suggests, so that people can find them easily and check that the label does not already exist. A reference file would also help ensure that people use whatever format is agreed upon for the references. Andrew On Tuesday, 6 September 2016 07:49:42 UTC+10, John H Palmieri wrote: > > > > On Monday, September 5, 2016 at 11:20:15 AM UTC-7, Johan S. R. Nielsen > wrote: >> >> leif writes: >> >> ... [HP] W. C. Huffman, V. Pless, Fundamentals of Error-Correcting >> >> Codes, Cambridge Univ. Press, 2003. >> > >> > Well, first of all it is stupid to use such a short abbreviation, even >> > without a year. Presumably it was introduced when references were >> > local, so we may create a (meta-)ticket to change all of such >> occurrences. >> >> Agreed. The inspiration for new developers in the Sage Development >> manual uses the citation label "[SC]": >> >> >> http://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings >> >> >> >> >> Is this sort of mess the reason Sphinx is so terribly slow, I >> wonder... >> > >> > Well, not that long ago, docbuilding in parallel wasn't even possible >> > (h/t mostly John Palmieri IIRC, with a few others); before, the whole >> > reference manual had been one monolithic block. >> > >> > Of course the documentation keeps growing (and hence also Sphinx' >> memory >> > footprint and runtime), but it was IMHO always double dog-slow. But >> > especially building plot* gets slower and slower because people keep >> > adding more and more "nice" things I guess. >> > >> > To me the most annoying thing is that "make doc" (which ptestlong for >> > example for no reason depends on) meanwhile even takes ages when Sphinx >> > does nothing, or almost nothing, because nothing changed. (My recent >> > impression is though that some files accidentally get touched somehow, >> > such that they to Sphinx look modified. I can't give any concrete >> > example, just noticed.) >> >> Yes, doing `make doc` goes through every chapter of the manual, very >> carefully determining that nothing changed. I often use "./sage >> -docbuild reference/<chapter> html" instead, but that seems even more >> fragile than regular doc-building. >> >> Jeroen Demeyer writes: >> > General comment to all people complaining about Sphinx: reviewing >> > existing Sphinx-related tickets such as #20577 will show that you >> > actually care and will encourage other Sage developers to continue >> > working on Sphinx. >> >> Thanks for your work! Are there tickets (or upstream-not-merged-changes) >> which would make Sphinx faster or have better, less fragile incremental >> building? >> >> Best, >> Johan >> > > Regarding speed, there are two issues: > > 1. Building the documentation from scratch. I don't know if we can expect > this to go any faster. The PDF version of the documentation is 3,474 pages > long. No, wait, that's just the contribution from references/combinat: the > whole reference manual is 18,442 pages long. I can build this on my machine > in about 8 minutes, and this does not seem unreasonable. Am I wrong about > this? (It could be sped up a bit for parallel builds if the largest pieces, > e.g., reference/combinat, were broken into smaller pieces, but I don't know > how much speed increase we can hope for.) > > 2. Incremental builds. I agree that this is not very fast, and it doesn't > play well when switching between git branches: too much of the > documentation is rebuilt, and the docbuild often fails (e.g., if Python > source files have been removed from one branch to another). I don't know > how to fix these issues. > > By the way, the main work for allowing parallel docbuilding was done by > Mitesh Patel, not me (although I helped a little). > > -- > 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.
