2011/12/1 Fernando Perez <fperez....@gmail.com>: > On Thu, Dec 1, 2011 at 2:56 AM, Friedrich Romstedt > <friedrichromst...@gmail.com> wrote: >> 1) Spanning paragraphs over equations. Paragraphs are in Docutils a >> nonstructured entity. In depends on the point of view if this is a >> design mistake or not. For the Sphinx purpose, it might be not, for >> the (e)paper document it probably is. I do not think we would like to >> discuss this here again, just to point it out. > > I don't mean to restart a discussion if this has already happened > here, but I'm very interested in this question and don't know what you > are referring to. Could you provide me with a quick pointer to the > relevant discussion if it happened before, or just a brief summary? > I'd greatly appreciate it...
I've put a thought that came up in https://groups.google.com/d/topic/sphinx-dev/2Du-mS16_aI/discussion here: http://friedrichr.blogspot.com/2011/11/text-formatting.html, but I recommend reading the discussion since I put emphasis on the programmatical-philosophical aspects of the problem in my blog post. I should probably rework it to include an introduction of the problem, and the philosophy only as a section .... the blog post worked out from a message that turned out to be too long to be sent to the list (I felt). So read the blog post as the last message in that discussion ... >> 2) Global References section. > > Is it not possible to enable global references for sphinx? I was wrong. In approx. Sphinx 0.9.0 it was not yet possible, but nowadays I read: "Standard reST citations (ref) are supported, with the additional feature that they are “global”, i.e. all citations can be referenced from all files." [http://sphinx.pocoo.org/rest.html#citations]. Sorry for that. > The reason I'm very interested in these issues is b/c the new > web-based notebook in ipython will eventually (it doesn't quite yet) > export to reST/sphinx for high-quality pdf production using the > sphinx-latex capabilities. So for us, it's really important to > understand what limitations may exist (and we might be able to fix > some of them, if it's doable). I might think, that this is a pretty good application. Saving a notebook as a pdf is very useful, because PDF is forward compatible ... it does not change so rapidly. I don't think the paragraph limitation is fixable, it's deeply rooted in docutils, where this is a major design decision (the decision what XML containers can contain which is exactly this). I think it wasn't the best decision, because it creates a lot of CSS overhead that could *possibly* be avoided by allowing more complex paragraphs. But I can only verify this on the example I gave in the discussion referenced above, otherwise it's just a gut feeling, influenced also by LaTeX experience. Guess that's kind of summary. Be sure it's biased ;-) Your mileage may vary. OTOH, seeing paragraphs as just what is done in Docutils of course makes things simpler, by having a clean notion of what a paragraph is, how it's formatted etc. But it seem to me, that this is an over-simplification, or at least the problems are then outsourced to CSS, just look at the source code of an rst2html or Sphinx generated document. This is the impression I got. It's nothing wrong with solving it via CSS, it's just more complicated and less maintainable IMHO. But I'm not gonna change it, since I'm happy with the Sphinx output, mostly. The formatting mistake pointed out by me in the discussion results, afair, from the omission of some docutils CSS classes in the Sphinx templates. It can be interpreted as a pointer towards the correctness of my statement "it is less maintainable". I would like to point emphasis on that Sphinx mostly works and is very valuable, although there are minor problems like mine which probably do not affect overall functionality. > With IPython, we'd like to shorten the > gap between interactive computational exploration and final > publication as much as possible, so that final paper/book outputs are > as reproducible as is realistic. One of the issues (IMO) that gets in > the way of easily reproducible computational results is the large > disconnect between original codes and final results: by the time > you've massaged your outputs into something publishable, you've long > stopped running your real codes. If we could get much closer to a > true 'executable paper', I think we'd make progress on this issue. > Hence, our interest in seeing how much we'll be able to use sphinx for > final paper/book production. I'm not a user on this, so I will probably not give a very knowledgable answer. I'm one of those guys who writes a Python script for generating figures and runs that over and over again until it works. IMHO, as said above, I don't think it's doable to do a publication right from the notebook, it's just a different medium, isn't it? But as I said, I find it valuable to store how it looks like, and if it is just for the printout for the lab book. For publishable things, I'm one those who write a LaTeX script ;-), seeing LaTeX as a programming language (actually it is, isn't it?). :-) > Thanks for any feedback, I like people who like feedback. :-) I always feel guilty when I've written too much :-) Friedrich P.S.: I would like to speculate how this misfit of ReST docutils XML to HTML originates. I think the docutils DOM (?) is just very appropriate to ReST, it describes everything that's in ReST appropriately. So people went on from this to generate HTML from it. And now, unfortunately, there's no such thing like a plain blank line in HTML (if it's proper). So we need CSS to replicate the blank lines as we find it heuristically approriate. Just a guess. I would understand it fully, I could feel with them :-) -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
