Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

## docutils-users — General discussions, questions, help requests.

You can subscribe to this list here.

2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 Jan Feb Mar Apr May Jun Jul Aug (3) Sep (15) Oct (21) Nov (18) Dec (59) Jan (43) Feb (35) Mar (78) Apr (65) May (163) Jun (169) Jul (137) Aug (77) Sep (47) Oct (27) Nov (43) Dec (68) Jan (61) Feb (39) Mar (11) Apr (42) May (86) Jun (82) Jul (24) Aug (26) Sep (37) Oct (62) Nov (131) Dec (43) Jan (31) Feb (56) Mar (65) Apr (165) May (106) Jun (97) Jul (65) Aug (150) Sep (78) Oct (115) Nov (41) Dec (26) Jan (50) Feb (39) Mar (56) Apr (67) May (89) Jun (68) Jul (116) Aug (65) Sep (58) Oct (103) Nov (28) Dec (52) Jan (92) Feb (60) Mar (124) Apr (96) May (69) Jun (79) Jul (25) Aug (22) Sep (7) Oct (17) Nov (27) Dec (32) Jan (57) Feb (87) Mar (51) Apr (43) May (56) Jun (62) Jul (25) Aug (82) Sep (58) Oct (42) Nov (38) Dec (86) Jan (50) Feb (33) Mar (84) Apr (90) May (109) Jun (37) Jul (22) Aug (51) Sep (93) Oct (86) Nov (31) Dec (62) Jan (33) Feb (57) Mar (62) Apr (43) May (30) Jun (49) Jul (20) Aug (40) Sep (152) Oct (38) Nov (15) Dec (32) Jan (29) Feb (25) Mar (65) Apr (45) May (27) Jun (11) Jul (14) Aug (8) Sep (13) Oct (117) Nov (60) Dec (19) Jan (23) Feb (32) Mar (24) Apr (41) May (56) Jun (24) Jul (15) Aug (11) Sep (26) Oct (21) Nov (12) Dec (31) Jan (32) Feb (24) Mar (39) Apr (44) May (44) Jun (8) Jul (9) Aug (12) Sep (34) Oct (19) Nov (5) Dec (9) Jan (22) Feb (12) Mar (7) Apr (2) May (13) Jun (17) Jul (2) Aug Sep Oct Nov Dec
S M T W T F S

1

2
(1)
3

4

5

6

7

8

9
(4)
10
(1)
11
(2)
12
(5)
13
(1)
14
(3)
15
(8)
16

17
(2)
18

19
(1)
20

21
(1)
22
(2)
23
(2)
24
(6)
25
(4)
26
(2)
27
(3)
28
(5)
29

30
(7)

Showing results of 60

<< < 1 2 3 (Page 3 of 3)
 Re: [Docutils-users] why docutils should reject Alan's proposal From: Paul Tremblay - 2011-11-12 03:38:45 On 11/11/11 8:06 PM, Alan G Isaac wrote: It would be more helpful if Alan had actually included examples of syntax markup and the resulting tree. Since he didn't, let me do that so everyone is clear on the intentions. Alan proposes that this syntax: a refernce [mycite{p33}]_ .. [mycite] reference Becomes this tree: a refernece mycite p33 ^^^^^^^^^^^^^^^^^^^^ reference Note the addition of the cite_arg element. This suggestion ignores the fundamental idea behind docutils, that it processes text to form a tree. This tree can then be converted into other forms, such as LaTeX (a non-tree structure) or XML, HTML, or OpenOffice (all trees). Alan proposes that docutils implement something for one type of writer (LaTeX) that will not work with other types of writers (OpenOffice, HTML, XML). So one could write a scientific paper intended for the web in reStructuredText, and still not have any bibliographic management. Such an approach is short-sighted. None-the-less, Alan makes a valid point. He at least wants the ability to post process the string created in the hypothetical cite_arg above. The above tree fragment: mycite p33 Can be processed by a further transform, depending on the writer, just before the text is actually written. The transform could be written later. For now, one has the option of either including literal text (for example "a reference [mycite{page 33}]_"), or of not using any optional arguments. To make this truly useful, however, I think we need to agree that there be more than one argument. If we are going to change the syntax of the reference citation, it makes more sense to make it flexible and logical. So, going with Alan's initial proposal (from a few weeks ago), the text could look like this: [mycite {page: 33}{vol: 2}]_ Note the difference here: there are now more than one argument. Each argument has a keyword that helps define the argument. The resulting tree would be: mycite 33 2 Let be clear here that I am not proposing that the arguments be constricted by any specific grammar. For example, this syntax would be also valid: [mycite {page: 33}{vol: 2}{spaghetti_monster: like speghatti}]_ mycite 33 2 like spaghetti Such a syntax would make post processing much easier and more sensible. In addition, I propose that an optional, simplified syntax with an implied argument be allowed. [mycite 33]_ 33 And: [mycite 33-44]_ 33-44 Other implied arguments could also be implemented, such as pages separated by commas. The obstacle to this implementation at this point are the normal obstacles: (1) Does everyone agree on the usefulness of the syntax? (2) Can the parser parse the syntax? Paul > Paul, > > I cannot tell from your post whether you actually > understand how BibTeX's optional text works. Do you? > Millions of users have found BibTeX pretty darn useful. > I ask yet again, what part of your critique would *not* apply > to BibTeX's handling of optional text? Can you please > respond to this question? (It provides important > context for the conversation.) > > I'm just asking we take a small step by adding functionality > that millions of BibTeX users have proved is useful. > > It would be one thing if you were proposing some better > way to move forward, but instead you seem to insist that optional > text not just be arbitrary optional text but come with a grammar. > As I explained multiple times, this is exactly what my > proposal intentionally does not do. > > My only proposal is that docutils support optional text > for citation references, instance by instance. > Yes: a single string. You ask "what use is that?"; well, > ask millions of BibTeX users. It is useful! > > Finally, you seem to think I am putting forward an > implementation proposal. I am putting forward only > a proposal that developers agree in principle to allow > optional text, and find a syntax to support it. > I've proposed one at the document level, one that > is easily parsed and backward compatible. Here is > another: use the vertical bar. > > [mycite|optional text]_ > > I am not in any way attached to this. I have also > urged that docutils treat the optional text as a simple > string and not commit to parsing it in any way, because > otherwise we need agreement on many things whereas > getting agreement even on allowing any extra information > at all will be hard to get. > > Note too that you offer an example where the citation > is changed by the optional text. That is not what > I proposed: the citation is what it is. The optional > text for the citation reference only affects that > particular instance of the citation reference. > (Again, compare with BibTeX.) E.g., [mycite{p.10}]_ > would become e.g. :: > > refid="mycite">mycitep.10 > > and then [mycite{vol.3,p.10}]_ would become e.g. :: > > refid="mycite">mycitevol.3,p.10 > > I am not proposing the details! The important thing is that the citation > would be unchanged. Both references would be to the same citation. > That is the only goal: to allow optional text in the citation references, > instance by instance. > > Finally, you can have what you would like even if > my wishes are accommodated. For example, suppose there > were agreement to allow optional text as I request, > perhaps using the vertical bar as above. Then when > you persuade everyone of a useful and meaningful > grammar for additional text, you could introduce > it using braces. If it is superior -- and honestly > I imagine it will be in every way aside from date > of implementation -- then use of the other syntax > will slowly die out. > > Alan > > > ------------------------------------------------------------------------------ > RSA(R) Conference 2012 > Save \$700 by Nov 18 > Register now > http://p.sf.net/sfu/rsa-sfdev2dev1 > _______________________________________________ > Docutils-users mailing list > Docutils-users@... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. 
 Re: [Docutils-users] why docutils should reject Alan's proposal From: Alan G Isaac - 2011-11-12 01:06:26 Paul, I cannot tell from your post whether you actually understand how BibTeX's optional text works. Do you? Millions of users have found BibTeX pretty darn useful. I ask yet again, what part of your critique would *not* apply to BibTeX's handling of optional text? Can you please respond to this question? (It provides important context for the conversation.) I'm just asking we take a small step by adding functionality that millions of BibTeX users have proved is useful. It would be one thing if you were proposing some better way to move forward, but instead you seem to insist that optional text not just be arbitrary optional text but come with a grammar. As I explained multiple times, this is exactly what my proposal intentionally does not do. My only proposal is that docutils support optional text for citation references, instance by instance. Yes: a single string. You ask "what use is that?"; well, ask millions of BibTeX users. It is useful! Finally, you seem to think I am putting forward an implementation proposal. I am putting forward only a proposal that developers agree in principle to allow optional text, and find a syntax to support it. I've proposed one at the document level, one that is easily parsed and backward compatible. Here is another: use the vertical bar. [mycite|optional text]_ I am not in any way attached to this. I have also urged that docutils treat the optional text as a simple string and not commit to parsing it in any way, because otherwise we need agreement on many things whereas getting agreement even on allowing any extra information at all will be hard to get. Note too that you offer an example where the citation is changed by the optional text. That is not what I proposed: the citation is what it is. The optional text for the citation reference only affects that particular instance of the citation reference. (Again, compare with BibTeX.) E.g., [mycite{p.10}]_ would become e.g. :: mycite p.10 and then [mycite{vol.3,p.10}]_ would become e.g. :: mycite vol.3,p.10 I am not proposing the details! The important thing is that the citation would be unchanged. Both references would be to the same citation. That is the only goal: to allow optional text in the citation references, instance by instance. Finally, you can have what you would like even if my wishes are accommodated. For example, suppose there were agreement to allow optional text as I request, perhaps using the vertical bar as above. Then when you persuade everyone of a useful and meaningful grammar for additional text, you could introduce it using braces. If it is superior -- and honestly I imagine it will be in every way aside from date of implementation -- then use of the other syntax will slowly die out. Alan 
 [Docutils-users] why docutils should reject Alan's proposal From: Paul Tremblay - 2011-11-11 23:28:07 Docutils mailing list: David Goodger has suggested that the two major reasons why reStrucuredText is not used for scientific documentation is that it cannot mange bibliographic references and it cannot include math. Recently, there have been some good steps forward in implementing math support (through converting LaTeX to MathML, for example). There have been no steps forward to handle bibliographic management. Alan Isaac has put forward some type of proposal, but I suggest docutils reject this proposal. In order for a proposal to be adopted, it must meet 2 criteria: (1) It must thoroughly explore the problem. The proposal must not only consider the actual reStructuredText syntax, but the needs of a different users. For example, the developers have considered the problem with tables and have realized that many users needed CSV tables, and then implemented this feature. Thought was given to the needs of users and the different scenarios. (2) A proposal must include examples of reStructuredText syntax and examples of how that syntax should be rendered in a tree. For example, the reSructuredText pattern Title === Gets rendered in the docutils tree as
Title Imagine if docutils did not have the heading element, and someone proposed that there should be a title just like in MS Word. What exactly does that mean? Does the user want to create a section, for example? Alan's proposal fails to meet either criteria. (1) First, he has not thoroughly considered the problem at hand. Bibliographic references can be quite complex. Consider: As Bergonzi notes (*Anatomy of Rome*, p33) As Bergonzi notes (*Anatomy of Rome*, p33-66) As Bergonzi notes (*Anatomy of Rome*, p33, p66) As Begonzi notes (*Anatomy of Rome*, p33-66, Vol1, p45, Vol 2) As Bergonzi and Jensen note (*Anatomy of Rome*, p33-66, Vol1, p45; *History of Italy*, p33) And so fourth. I have done some work in the past on just this issue, painstakingly going through style manuals gleaning examples. That is how I know about the complexity of the issue. Alan's proposal has not considered any of these issues. Instead of presenting the full problem and then showing how his proposal would handle them, he has merely given one or two examples, and then in a very vague way. He has not presented proposed syntax for these examples. Instead, he has presented rambling discourse on the need to accept his proposal, and how it works in bibtex. Such a proposal neither addresses the specific problem nor gives a solution. A serious proposal includes specific syntax for all the potential situations. Alan either seems unaware of the complexity of the problem, or does not care to address it. (2) Alan proposes no idea of how the docutils tree should render his proposal. As it stands now, the following syntax: a refernece [foo]_ .. [foo] reference Gets rendered as a refernece foo reference No spaces are allowed, and brackets are not allowed. The text inside the brackets gets assigned an ID, which should match a the backrefs attribute in the citation element. Alan suggests: [mycite{mytext}]_ From here, he does not suggest how he wants the new tree to look. Presumably, he wants the text "mycite" to link to the full citation, and the string "mytext" to somehow be extra. But from here, his proposal is too vague to be taken seriously. Does he want the "mytext" dumped as a string in its own element? If so, then how about when there are multiple references? For example: As Bergonzi and Jensen note [Anatomy{p33-66Vol1,p45;Vol2p33-44}]_ Becomes: p33-66Vol1,p45;Vol2p33-44 But what use is that? The other element now contains a string of text that is almost useless to an external writer or parser. Perhaps he wants: As Bergonzi and Jensen note [Anatomy{p33-66}{Vol1}{p45}{Vol2}{p33-44}]_ .. [Anatomy] *Anatomy of Rome*, etc to become:

33-66

1

45

2

33-44

It is hard to say, because Alan's proposal does not contain any specifics. He keeps insisting that it is not important how the rest of the text that is not the ID gets handled, but that seems unworkable, namely because his solution does not put fourth a solution to bibliographic management. It basically requires a partial solution that does not further the goals of reStructredText. Developers would have to develop code only to have to go back later and develop more code, or switch the code they have. Alan seems unaware that a reStructuredText document gets rendered to a tree before it gets rendered to a LaTeX document, and hence his proposal remains too vague to be workable. I suggest that Alan do 3 things in order for his proposal to go forward: 1. Use specific language when talking about this problem so that we are not talking past each other 2. Provide the syntax for complex citation references, not just simple references that have one page. 3. Provide specifics on how he wants these citations parsed, preferably in a tree, or, if he does not feel comfortable with that, something equivalent. I don't think implementing poorly thought-out proposals further reStructuredText Paul 
 Re: [Docutils-users] Two ideas for implementation From: Martin Bless - 2011-11-11 09:38:10 [Alli Quaknaa] wrote & schrieb: (1) >First idea is inspired by a recent post [1] in this list asking about >the "field-list-table" directive. Is there still interest in this? Is >someone working on it at the moment? Yes, yes. I'am the one who asked. We still need it. And I'm working on that at the moment. And, your're right: It's not that very difficult. I've got a first version doing the basic stuff ready and working here already. So you could leave this "field-list-table" topic up to me. I will continue that work when there's a next time slot free. Currently my code isn't written well and I want to add "rowspan" and "colspan" capabilities. That's a bit more tricky. And I'm not sure yet what kind of :options: should be possible. So I've switched to improving an existing 'html2rst' converter to also handle tables. I am dreaming of roundtrip capabilities: html -> rst -> html -> rst -> ... with table structure being maintained. I will be glad to present the stuff here or come back for help. (2) >The second idea is a much more complex one. Yes, do that :-) As I wrote already the http://typo3.org community has decided to switch to ReST documentation format lately. And others of us are trying to care about the LaTeX stuff. I am not in that and cannot help with suggestions here. But I know there is much need in that area. So I'd love to see you following your idea (2)! Cool, cool, cool, I'm feeling excited! Martin -- http://mbless.de 
 [Docutils-users] Two ideas for implementation From: Alli Quaknaa - 2011-11-10 23:28:06 Hello everyone, I'm a regular user and a great fan of docutils and ReST; I use it to write reports and other documents and I even wrote my bachelor thesis in it. Thank you all for the hard work you put in the project! This year at school I signed up for an open-source programming class which includes participating in an actual project; I'd like to contribute something to Docutils. There are two ideas I have and I need to decide between. My concern is mostly about how long would each idea take to implement and how complicated it would be; I'm fluent in Python and I wrote some custom extensions for docutils before, but I'm still no expert on how docutils work internally. First idea is inspired by a recent post [1] in this list asking about the "field-list-table" directive. Is there still interest in this? Is someone working on it at the moment? As far as I can tell this seems like a rather easy thing to do, basically just transforming the field list into a table in the internal tree representation. Am I missing something (apart from correct terminology)? The second idea is a much more complex one. I'm not a huge LaTeX fan; it does the job for me most of the time, but without rst2latex I'd be lost. Adjusting stuff by hand typically takes too much tweaking and I'm not very satisfied with the documentation. On the other hand, the documentation of ConTeXt [2] is very nice and well organized and I like the system more in general. So I thought about creating a ConTeXt writer, to have a rst2context tool in the end. Again, if I understand correctly, that woul mean taking some of the existing *tex writers and modifying it accordingly. Is there a sample document using all directives, where I would be able to test how far I progressed? What are the standards for creating new writers and for accepting them into upstream? What are your thoughts? Is there some other feature/bug that is more important, yet easy enough for me to work on? Something from the docutils ToDo [3] perhaps :) ? Thanks in advance for your suggestions! al-Quaknaa P.S.: I'm away for the weekend so I may not respond immediately, but I will eventually. [1] http://article.gmane.org/gmane.text.docutils.user/6456 [2] http://wiki.contextgarden.net/Main_Page [3] http://docutils.sourceforge.net/docs/dev/todo.html 
 Re: [Docutils-users] newpage in restructuredtext From: Guenter Milde - 2011-11-09 22:34:06 On 2011-11-09, Fischer, Felix wrote: >> What do you want to achieve? >> A new page in your LaTeX generated .pdfs or also in .odt? >> Or should each section start on new page automatically? > I would be glad, if newpage would also work in odt. I guess, each > section/subsection on a new page would be the best solution! This looks very much like a task for a custom style sheet. I don't know whether/how this can be achieved in ODT. I know that it is possible with a custom style or just LaTeX preamble code with LaTeX. However, I don't know the details so you will need to search the web or ask the TeXperts about "LaTeX, start every section on a new page". Günter 
 Re: [Docutils-users] newpage in restructuredtext From: Fischer, Felix - 2011-11-09 14:00:56 Dear Peter, Thanks for your suggestion! > But I can't decide, whether this already what you are looking for. > > What do you want to achieve? > A new page in your LaTeX generated .pdfs or also in .odt? > Or should each section start on new page automatically? I would be glad, if newpage would also work in odt. I guess, each section/subsection on a new page would be the best solution! Best, Felix -----Ursprüngliche Nachricht----- Von: Peter Funk [mailto:pf@...] Gesendet: Mittwoch, 9. November 2011 11:39 An: docutils-users@... Betreff: Re: [Docutils-users] newpage in restructuredtext Hello, Fischer, Felix (Mittwoch, den 09.11.2011 um 11:12): > Dear List, > > > > i use restructuredtext to sweave my statistical analysis from R into html, odt > and pdf (via latex). However, to improve readability I would like to start a > section on a new page. Is there any kind of a “newpage” command in > restructuredtext? There is already a way to force a page break in LaTeX described in the docutils Documentation: Commands directly to LaTeX ========================== By means of the reST-raw directive one can give commands directly to LaTeX, e.g. forcing a page break:: .. raw:: LaTeX \newpage But I can't decide, whether this already what you are looking for. What do you want to achieve? A new page in your LaTeX generated .pdfs or also in .odt? Or should each section start on new page automatically? 
 Re: [Docutils-users] newpage in restructuredtext From: Peter Funk - 2011-11-09 11:09:19 Hello, Fischer, Felix (Mittwoch, den 09.11.2011 um 11:12): > Dear List, > > > > i use restructuredtext to sweave my statistical analysis from R into html, odt > and pdf (via latex). However, to improve readability I would like to start a > section on a new page. Is there any kind of a “newpage” command in > restructuredtext? There is already a way to force a page break in LaTeX described in the docutils Documentation: Commands directly to LaTeX ========================== By means of the reST-raw directive one can give commands directly to LaTeX, e.g. forcing a page break:: .. raw:: LaTeX \newpage But I can't decide, whether this already what you are looking for. What do you want to achieve? A new page in your LaTeX generated .pdfs or also in .odt? Or should each section start on new page automatically? Viele Grüße nach Berlin, Peter Funk -- Peter Funk, home: ✉Oldenburger Str.86, D-27777 Ganderkesee mobile:+49-179-640-8878 phone:+49-421-20419-0 ; office: ArtCom GmbH, ✉Haferwende 2, D-28357 Bremen, Germany DRUPA 3.5.-16.5.2012: Besuchen Sie uns in Halle 4 auf Stand B02 
 [Docutils-users] newpage in restructuredtext From: Fischer, Felix - 2011-11-09 10:13:00 Attachments: Message as HTML Dear List, i use restructuredtext to sweave my statistical analysis from R into html, odt and pdf (via latex). However, to improve readability I would like to start a section on a new page. Is there any kind of a "newpage" command in restructuredtext? Best, Felix Dr. rer. nat. Dipl.-Psych. Felix Fischer Institut für Sozialmedizin, Epidemiologie und Gesundheitsökonomie Charité - Universitätsmedizin Berlin Luisenstrasse 57 10117 Berlin Tel: 030 450 529 104 Fax: 030 450 529 902 http://epidemiologie.charite.de; 
 Re: [Docutils-users] Separate html file for each chapter From: TP - 2011-11-02 03:28:27 On Mon, Oct 31, 2011 at 7:21 AM, Bob Plantz wrote: > My book is already written in LaTeX, which is sort of at the opposite end of > the toolchain path from rst. Converting it to epub is turning out to be a > real chore, but an interesting learning experience. It's teaching me that my > source should be as simple as possible, which allows for more diverse paths > to the final outputs. BTW, sphinx already does "experimental" output to epub. See http://sphinx.pocoo.org/config.html#options-for-epub-output and http://sphinx.pocoo.org/faq.html#epub-info for more info. You can use MathJax (http://www.mathjax.org/) with sphinx now (http://sphinx.pocoo.org/ext/math.html#module-sphinx.ext.mathjax). This lets you use latex within rst files. However, epub support of Mathjax is still in the future. The thread "MathJax and epub3" (http://groups.google.com/group/mathjax-dev/browse_thread/thread/1190dc76b7b88a02) and searching http://groups.google.com/group/mathjax-users/ for "epub" will show you the relevant current discussions. 

Showing results of 60

<< < 1 2 3 (Page 3 of 3)