very interesting article! after reading url that you have posted, have you the rst source to public view, please if possible we try to simulate this in debian public environment of libraries http://www.telecentros.sp.gov.br/. thanks for these very nice kind of use.
2011/1/29 foobaron <cjlee...@gmail.com> > Hi, > I've been using Sphinx a long time for software projects and more > recently for writing all my scientific papers. I love being able to > run it right on my iPad to view and edit papers with lots of equations > (HTML output with jsMath), and at the same time generate latex & PDFs > I can circulate to people for comments. > > I've found that the problems start when I want to submit the paper to > a journal, because each journals requires the latex source of the > manuscript to conform exactly to their custom latex template, which of > course Sphinx's latex output does not. After studying how Sphinx / > docutils generate latex output, I decided not to mess with that code > at all but instead just wrote a separate Python script to extract the > relevant sections of Sphinx's latex output and insert them into the > latex template supplied by the journal. This is pretty easy, works > great, and is easy to adapt to different journals (so far I've done it > for PNAS, PLOS, and Information; if people want me to post an example > rewriter script I can do that). But it feels like a kluge; it seems > like lots of people want this kind of latex output customization and > we should instead all be using docutils latex templates etc. For > example, if Sphinx alters little details of the latex it outputs, that > might make my re-writer script stop working (because it has to search > for specific strings in Sphinx's output, and transform them). An > example of a latex paper produced this way is viewable here: > http://www.mdpi.com/2078-2489/2/1/17/ > > I'm totally sold on Sphinx as my long-term solution for being able to > "cross-compile" my content to many different outputs. I would now > like to work on this latex output template customization problem in a > general way that would be usable, extensible and customizable by > others. My question is what approach Sphinx developers would > recommend. I'll quickly note a few requirements: > > - this is not just a matter of changing a template file. The Sphinx > code itself contains many fragments of latex that must be customized > for each possible output. For example, > sphinx.ext.mathbase.wrap_displaymath() outputs displaymath using the > non-standard environments "gather" and "split". This does not match > any scientific journal's template, so either this Sphinx code itself > must change, or we are stuck with my klugey approach (external scripts > that rewrite the latex output by Sphinx, inserting it into a journal's > template). > > - scientific journals supply precise templates and demand that authors > follow them exactly. Nowadays they input the latex file directly into > their typesetting production, so to ensure a uniform appearance and > standard across all the papers they publish, they *require* that the > manuscript follow the template. As an author, I cannot deviate from > their template at all. For example, they won't permit the inclusion > of any packages other than a specified list that is used by their > template. Unfortunately, much of the Sphinx code for latex support > assumes the use of many custom packages. Again either that code has > to change, or we're stuck with the external re-writer script approach. > > - this will require user-settable options for what to do with figures > and tables. For example, during the initial submission / review > phase, PLOS journals want the figures and tables included at the end > of the manuscript (not in the middle of the text where Sphinx inserts > them). However, once the paper is accepted for production, they want > *only* the figure legends included at the end of the manuscript (i.e. > do not include the figure images in the manuscript at all; they must > be submitted separately). With my re-writer script this is easy; it > just takes an optional argument that controls whether it includes the > figures in the output or not. > > I'd like to get some advice about what approach people think would be > best. A few options come to mind: > > - external rewriter scripts: the rewriter takes a Sphinx latex output > file and a latex template file, and inserts the relevant pieces of > content into the template. This could be designed in a relatively > modular way. I.e. a parser that extracts relevant sections from the > Sphinx latex output; a "standardizer" that removes non-standard things > like "gather" and "split". Then for each output target there could be > a very small amount of code that processes journal-specific options > like "submission format" vs. "production format". While in my > experience such "re-writers" are compact and easy to write, there is > clearly a disadvantage that if Sphinx changes its latex output, that > could break the parser or standardizer. > > - for this reason, it might make sense to make the "parser" and > "standardizer" components of this actually part of the sphinx > codebase, along with a bunch of automated tests that ensure they are > working. Since these pieces must be kept in sync with the Sphinx > code, that argues that they should be part of the Sphinx mercurial > tree. Then the set of journal-specific "writer" scripts (which will > be *very* simple, since all they have to do is process various little > options) could either also be included with Sphinx, or distributed as > a separate project. > > - "the full Monty": instead of using an external re-writer script, we > modify the Sphinx latex code (e.g. sphinx.ext.mathbase, > sphinx.writers.latex) to make it easy to customize the latex output in > a truly general way (i.e. to produce output that does *not* assume non- > standard packages, that inserts directly into any template file the > user specifies, etc.). Having browsed the sphinx code a bit, this > seems like a fair amount of work, as it requires understanding what > both docutils and sphinx are doing to produce the latex output, and a > fair amount of code is involved... > > All comments and suggestions welcome. Sorry for the long post! > > -- Chris Lee > > -- > 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<sphinx-dev%2bunsubscr...@googlegroups.com> > . > For more options, visit this group at > http://groups.google.com/group/sphinx-dev?hl=en. > > -- gilberto dos santos alves (11) 8646-5049 são paulo - SP - Brasil -- 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.
