From: Kent L. <ke...@br...> - 2013-02-25 19:50:42
|
Hello, As expected I can create docutils option_list output with the following restructured text: -c clear logs -d debug mode -D for Mac OS X launchd, don't fork -q min run for specified minutes then shutdown -r min run for specified minutes then restart -n number set maximum number of packets to read My problem is that I have some lists of options that are in non-standard format and thus are not recognized by docutils as an option_list. For example: -select expr select matching source names -start {pktid|time} set starting point for reading For lists such as these, I need to produce the output option_list by hand. I have attempted to clone the format of the option_list with experiments such as follows: .. list-table:: * - -select *expr* - select matching source names * - -start *{pktid|time}* - set starting point for reading This almost works, however the font used for the options and option-arguments, and the spacings used for the table, do not match what comes out of the option_list construct. What restructured text directive and what directive options do I need to reproduce exactly the format of the option_list ? Thanks, Kent -- Kent G. Lindquist, Ph.D. Boulder Real Time Technologies, Inc. 2045 Broadway Street, Suite 400 Boulder, CO 80302 USA +1-720-274-0098 FAX: +1-720-274-0096 ke...@br... |
From: David G. <go...@py...> - 2013-02-25 21:20:22
|
On Mon, Feb 25, 2013 at 12:49 PM, Kent Lindquist <ke...@br...> wrote: > Hello, > > As expected I can create docutils option_list output with the following > restructured text: > > -c clear logs > -d debug mode > -D for Mac OS X launchd, don't fork > -q min run for specified minutes then shutdown > -r min run for specified minutes then restart > -n number set maximum number of packets to read > > My problem is that I have some lists of options that are in non-standard > format and thus are not recognized by docutils as an option_list. For > example: > > -select expr select matching source names > -start {pktid|time} set starting point for reading > > For lists such as these, I need to produce the output option_list by hand. An alternative is to adapt your list as follows: --select expr select matching source names --start expr set starting point for reading (expr = pktid or time) > have attempted to clone the format of the option_list with experiments such > as follows: > > .. list-table:: > > * - -select *expr* > - select matching source names > * - -start *{pktid|time}* > - set starting point for reading > > This almost works, however the font used for the options and > option-arguments, and the spacings used for the table, do not match what > comes out of the option_list construct. > > What restructured text directive and what directive options do I need to > reproduce exactly the format of the option_list ? My first reaction is to answer "mu" -- unask the question. Rethink the problem, maybe use the workaround above. Why do you want to exactly reproduce a construct without using that construct? Seems like you'd be going to a lot of effort for little return. If you insist on going this way, I'd suggest a table with inline literals: .. class:: borderless ================= ====================================================== ``--select expr`` select matching source names ``--start expr`` set starting point for reading (expr = pktid or time) ================= ====================================================== This won't give you the italics, but that would be more difficult to get. You could use a table without inline literals, but inline markup: .. class:: my-option-list ================= ====================================================== \--select *expr* select matching source names \--start *expr* set starting point for reading (expr = pktid or time) ================= ====================================================== The backslashes prevent the options from being parsed as option lists. You'd have to figure out the "my-option-list" style to apply. I'm pretty sure it can be done, but I'd have to look it up. -- David Goodger <http://python.net/~goodger> |
From: Kent L. <ke...@br...> - 2013-02-25 21:39:27
|
Thanks David. > > An alternative is to adapt your list as follows: > > --select expr select matching source names > --start expr set starting point for reading (expr = pktid or time) The main problem was actually not with the '{pktid|time}' argument, it was with the multi-letter options preceded by only a single hyphen. Were I to double the hyphen so those options conform to POSIX usage, as you suggest, the option_list parsing would recognize them properly as options, however they would then no longer match the multi-million line code-base I'm documenting. > My first reaction is to answer "mu" -- unask the question. Rethink the > problem, maybe use the workaround above. Why do you want to exactly > reproduce a construct without using that construct? First of all I like the looks of it, it's compact and elegant; second I'd like to use the option_list auto-parsing for most of the code base, most of which has POSIX-compliant options. That would mean I would have to hand-construct just a few option tables for the non-POSIX options, however I'd like them to match the style of everything else. > Seems like you'd > be going to a lot of effort for little return. Well, I was hoping it would be easy. > You could use a table without inline literals, but inline markup: > > .. class:: my-option-list > > ================= ====================================================== > \--select *expr* select matching source names > \--start *expr* set starting point for reading (expr = pktid or time) > ================= ====================================================== > > The backslashes prevent the options from being parsed as option lists. > You'd have to figure out the "my-option-list" style to apply. I'm > pretty sure it can be done, but I'd have to look it up. I guess that was the point of my question, though perhaps as a restructured-text newbie I didn't pose it well. How do I figure out, cast, and invoke the "my-option-list" style to match the installed default? Web-surfing and docutils source-code diving haven't yet proven fruitful for me. I'm not sure where to look. If this is truly a big challenge I may indeed have to punt and do something approximate as you suggest. Clearly the docutils package knows somewhere how to format option_list output tables, so I was hoping it wouldn't be too much of a treasure hunt to reproduce its recipe for that. Clues welcome -- Thanks, Kent |
From: David G. <go...@py...> - 2013-02-25 21:52:43
|
On Mon, Feb 25, 2013 at 3:38 PM, Kent Lindquist <ke...@br...> wrote: > > You could use a table without inline literals, but inline markup: ... > > The backslashes prevent the options from being parsed as option lists. > > You'd have to figure out the "my-option-list" style to apply. I'm > > pretty sure it can be done, but I'd have to look it up. > > I guess that was the point of my question, though perhaps as a > restructured-text newbie I didn't pose it well. How do I figure out, cast, > and invoke the "my-option-list" style to match the installed default? Assuming you want HTML output, that's a CSS question -- stylesheets. You'd have to write a style to target the first column of the table and set the typeface. I can't help you beyond that. > Web-surfing and docutils source-code diving haven't yet proven fruitful > for me. I'm not sure where to look. If this is truly a big challenge I may > indeed have to punt and do something approximate as you suggest. It's not such a huge challenge, assuming you know about HTML stylesheets (CSS). If you don't, then it's a lot to learn. > Clearly the > docutils package knows somewhere how to format option_list output tables, so > I was hoping it wouldn't be too much of a treasure hunt to reproduce its > recipe for that. Clues welcome -- It's not that simple. Docutils parses an option list (recognizes the various parts), then formats it using dumb HTML. Look at the HTML underlying an option list (e.g. http://docutils.sourceforge.net/docs/user/rst/demo.html#option-lists) and you'll see what the output is like. But there's no way to get exactly that kind of output from Docutils without actually creating an option list. There's no way to "reproduce its recipe" without creating a recognizable option list for Docutils to parse. You can't "trick" Docutils in the way I think you're hoping, sorry. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2013-02-26 09:17:46
|
On 2013-02-25, David Goodger wrote: > On Mon, Feb 25, 2013 at 3:38 PM, Kent Lindquist <ke...@br...> wrote: > It's not that simple. Docutils parses an option list (recognizes the > various parts), then formats it using dumb HTML. Look at the HTML > underlying an option list (e.g. > http://docutils.sourceforge.net/docs/user/rst/demo.html#option-lists) > and you'll see what the output is like. But there's no way to get > exactly that kind of output from Docutils without actually creating an > option list. There's no way to "reproduce its recipe" without creating > a recognizable option list for Docutils to parse. You can't "trick" > Docutils in the way I think you're hoping, sorry. Another option would be to modify the parser to recognize the non-standard multi-letter options. This would require some insight into the inner workings of Docutils, though. There is some documentation on the Docutils.sf.net site and the open source. Günter |