Hello and feedback
Hi, all. I'm a technical writer who has been looking for a way to allow my subject-matter experts (programmers and engineers) to contribute to the maintenance of documentation, freeing me to get on with writing some much- needed new documentation. These people are not willing to learn a new software tool. They'd really like to use Word, but that's simply a big, big mistake: it will crap out on us as the documents get big and complex. I'd like to use DocBook XML, but it's unweildly for them and difficult to read without an XML-aware editor -- which would be a new software tool, which they don't want. So it looks like structured text is the solution: as long as I can transform it into DocBook XML, so that I can import it into my layout app and generate a PDF in under five minutes, things will be cool. And as I improve the XSL, I can even bypass the layout app, which means they can publish straight to PDF themselves, no worries. After chasing a few false leads, ReST appears to be the best candidate for accomplishing what I want. The ASCIIDoc project was *almost* there, but lacked a few key pieces. I have spent the past couple days transforming a moderately complicated document to ReST. The transformation is not complete: there are some missing pieces. You can download the zipfile from http://www.sfu.ca/~priest/VRAS.zip The two key missing puzzle-pieces are as follows: - I am unable to insert Unicode character entities into the text. Substitutions are the answer, so I've created a |subst| replace:&xAAA; table, as included in the zipfile. Alas, the DocUtils insist on <PRE>coding or &-substituting the replacement text. If this is fixed (perhaps by a "replaceliteral:" role), DocUtils will be much improved. - I am unable to use regex macros to manipulate the input text. There are two uses for this: 1) To do standardized typographic replacement on naive-user's text. For instance -- in print documentation -- the long dash, as I just used it, should be replaced using an em-dash surrounded by thin spaces. This is a detail that no naive user should have to worry about: that's my job as technical writer. Likewise, certain measurement units require marking-up: I'd like my naive users to write "36.8degrees" and get 36.8[degree sign], or 10m3 and get 10m[superscripted 3]. .. use the formal en-dash with number ranges .. regex:: ([0-9]+?)-([0-9]+?) = \1–\2 Note that the parenthesis in the prefix part of the equation indicate grouping: the regex says to look for one-or-more numbers (and remember them), a hyphen, and one-or-more numbers (and remember them, too). The postfix equation says to insert the first memorized group, an en-dash, and the second memorized group. If a file has a regex definition, it will be run before all other macros and substitutions, mais non? I think so. 2) To supplement the :role:` ` coding. In particular, the software documentation needs to indicate GUI elements. In HTML they would be rendered bold; in DocBook as <guilabel>. It would be appropriate for the source text to read " open the :gui:`File` menu and choose :gui:`Save` ". A :role: transformer program would be overkill for this. All that is needed is the ability to run an appropriate regex against the enclosed text, appropriate being defined by the destination file type. .. role:: html <B>:gui:</B> .. role:: docbook <guilabel>:gui:</guilabel> Note that DocUtils will need substitute the content of the interpreted text where the role label is shown. Thus :gui:`File` becomes <B>File</B> and <guilabel>File</guilabel>, respectively. DocUtils will have to match its destination file type to the appropriate role substitution, of course. I think the ideas I have presented here will allow ReST to be used far more broadly. It is currently at the very cusp of being used for general technical writing. I believe that as long as ReST can be converted to DocBook XML, it stands a very good chance of becoming a "front-end" replacement for DocBook XML. Not that I'm knocking DocBook, but it is often overkill for most purposes. I am now subscribed to the doc-sig list, daily digest format. Please take a look at my sample file, http://www.sfu.ca/~priest/VRAS.zip , for a demonstration of ReSTs application in moderately complex print documentation for a hardware and software product. (there are some other gaps, but I see that they've been addressed by others. Figure/Table autonumbering and referencing are a biggie. I see that someone has suggested a naming convention to allow referencing, and the autonumbering shouldn't be any problem at all, so I anticipate a solution is on the way.) Thanks for reading, david
David Priest wrote:
The two key missing puzzle-pieces are as follows: - I am unable to insert Unicode character entities into the text.
As I recently wrote on the docutils-users mailing list, With Unicode and encodings available (UTF-8, Latin-1, etc.), we can directly code as \u00A0 or \xA0. Same with soft hyphens (: \u00AD or \xAD), and any other Unicode character. This lessens (eliminates?) the need for the "escape sequence -> concrete character" kind of character processing. <http://article.gmane.org/gmane.text.docutils.user/190> Why are you unable to insert the actual, encoded characters into the text? What *are* you able to insert? What encoding are your files using? What platform (OS, editor, etc.)? It could be that you *can* insert real characters but don't know it. In any case, the world is moving inexorably towards Unicode. I don't see the point in complicating reStructuredText in order to duplicate what can be had for free with properly encoded input files.
Substitutions are the answer, so I've created a |subst| replace:&xAAA; table, as included in the zipfile. Alas, the DocUtils insist on <PRE>coding or &-substituting the replacement text.
XML character entities (&xNNNN;) are unknown to reStructuredText and are the wrong way to do it. Docutils is correct in substituting "&" in HTML output for every "&" in the input file (how could it tell the difference between *using* an XML character entity and just *talking* about one?). Your substitution table idea ought to work though, but you need to use real characters instead of "&xNNNN;" in it. Use a character encoding that contains all the characters you want -- Latin-1 if that's enough, your platform's native encoding (e.g. a Windows CP-* encoding), or UTF-8 for full Unicode capability. If your normal text editor can't handle the encoding you choose, use Emacs or VIM; if you can't handle them, get one of your programmers to help. It will be limited to the one file. For this to work, the encoding of the substitution table file has to be the same as that of the input file. Alternatively, some work has to be done on the Docutils code to allow different encodings. Also, the "\ " (backslash-space) escape sequence trick (also <http://article.gmane.org/gmane.text.docutils.user/190>) needs to be implemented to allow for character-level inline markup or substitutions inside words. The implementation should be easy.
- I am unable to use regex macros to manipulate the input text. There are two uses for this:
1) To do standardized typographic replacement on naive-user's text. For instance -- in print documentation -- the long dash, as I just used it, should be replaced using an em-dash surrounded by thin spaces. This is a detail that no naive user should have to worry about: that's my job as technical writer. Likewise, certain measurement units require marking-up: I'd like my naive users to write "36.8degrees" and get 36.8[degree sign], or 10m3 and get 10m[superscripted 3].
.. use the formal en-dash with number ranges .. regex:: ([0-9]+?)-([0-9]+?) = \1–\2
As I said in private email, at first glance, I doubt it [a regex substitution mechanism] will make its way into the Docutils/reStructuredText core. Such a function could easily be handled by pre-processing though. A script could convert ' -- ' into a UTF-8 em-dash, etc. Such a pre-processing system *could* be made part of Docutils, but separate from the core code I think. I realize that there is a problem with pre-processing. "10m3" inside a paragraph and "10m3" inside a literal block or inline literal should probably be handled differently, and a simple pre-processor would find it difficult to differentiate. Personally, I would go with an 80/20 auto/manual system. Write a quick script (or Emacs lisp function) to do the changes (convert "10m3" to "10m\ :sup:`3`", for example) and verify manually. If you try to add this conversion to the processing pipeline (in whatever form), there will someday be an exception where you *won't* want the conversion to take place. OTOH, if a good design appears and somebody implements it, who knows? The idea needs a lot of fleshing out first though. As with the substitution table file idea, "–" is no good; it would have to be a properly encoded en-dash character.
Note that the parenthesis in the prefix part of the equation indicate grouping: ...
I don't think we need a lesson in regular expression syntax, thanks. ;-)
If a file has a regex definition, it will be run before all other macros and substitutions, mais non? I think so.
What "other macros"? reStructuredText doesn't have macros.
2) To supplement the :role:` ` coding. In particular, the software documentation needs to indicate GUI elements. In HTML they would be rendered bold; in DocBook as <guilabel>. It would be appropriate for the source text to read " open the :gui:`File` menu and choose :gui:`Save` ". A :role: transformer program would be overkill for this. All that is needed is the ability to run an appropriate regex against the enclosed text, appropriate being defined by the destination file type.
There's absolutely no need for any regex substitution here. That's exactly what the Writers are for. The ":gui:`File`" input may become "<gui>File</gui>" in the internal document tree. The HTML Writer would write it with bold (or, better yet, with <span class="gui">, made bold by the stylesheet). The DocBook Writer would write it with <guilabel>. There has been some discussion about parameterizing the interpreted text system somehow, to avoid proliferation of element types (gui, keypress, etc.). No decision or action yet.
(there are some other gaps, but I see that they've been addressed by others. Figure/Table autonumbering and referencing are a biggie. I see that someone has suggested a naming convention to allow referencing, and the autonumbering shouldn't be any problem at all, so I anticipate a solution is on the way.)
They're on the To Do list, but I don't know when they'll be implemented. Contributions welcome! -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
XML character entities (&xNNNN;) are unknown to reStructuredText and are the wrong way to do it. Docutils is correct in substituting "&" in HTML output for every "&" in the input file (how could it tell the difference between *using* an XML character entity and just *talking* about one?). The charent pattern can be detected easily enough, and the "&" encoding skipped for those entities. If you want to talk about an entity directly,
There's absolutely no need for any regex substitution here. That's exactly what the Writers are for. The ":gui:`File`" input may become "<gui>File</gui>" in the internal document tree. The HTML Writer would write it with bold (or, better yet, with <span class="gui">, made bold by the stylesheet). The DocBook Writer would write it with <guilabel>. The problem with implementing it as a Writer is that Writers don't
There has been some discussion about parameterizing the interpreted text system somehow, to avoid proliferation of element types (gui, keypress, etc.). No decision or action yet. If "parameterizing the interpreted text system" means that simple role substitutions -- the kind that can be handled by regex -- can be placed within the source text files, great! It makes the source text more
I'm feeling that I've perhaps pissed in someone's cornflakes, but I'm going to respond anyways. If I've offended, I apologize profusely: no offense was intended. On Sat, 15 Mar 2003 01:01:25 -0500, David Goodger <goodger@python.org> wrote: literalizing it would do the trick. In all other cases the ampersand can be safely encoded. But the substitution table using "proper" characters is good enough, although I'm not entirely sure that all backends output will be able to deal with two-byte Unicode. travel with the source text files. If I send you a ReST file with :gui: roles in it, what's your DocUtils installation going to do with it? portable. If the role can't be handled by a regex, then of course it's going to require a Writer. (Although... if one could embed a Python script... but, no. That's verging on silly.) And if this email has been scrunched into a blob, I apologize. I assure you that there are blank lines scattered throughout it. I've tossed extra space characters in them, too. But my email client may still toss them aside. I have submitted a bug report.
[David Priest]
I'm feeling that I've perhaps pissed in someone's cornflakes, but I'm going to respond anyways. If I've offended, I apologize profusely: no offense was intended.
No offense perceived or taken. We're just debating the technical issues; nothing personal. Sorry if it seemed too blunt, but email tends to look that way. I don't have the time to be super-friendly or the inclination to sprinkle smilies throughout. When discussing issues via email, one needs a thick skin. Assume that the writer is smiling continuously, trying to help, which I was and am. [David Goodger]
XML character entities (&xNNNN;) are unknown to reStructuredText and are the wrong way to do it. Docutils is correct in substituting "&" in HTML output for every "&" in the input file (how could it tell the difference between *using* an XML character entity and just *talking* about one?).
The charent pattern can be detected easily enough, and the "&" encoding skipped for those entities. If you want to talk about an entity directly, literalizing it would do the trick. In all other cases the ampersand can be safely encoded.
By literalizing do you mean ``inline literals`` or literal blocks? That's not always acceptable. I might want to say The '&' entity is used by HTML and XML to represent the '&' character. I shouldn't have to use inline literals here. Docutils uses Unicode internally, and I don't see a need for it to grow a character entity subsystem. So far, you're the only one who has asked for one, and that's not convincing enough. I suspect that you may be asking Docutils to cover a deficiency in your toolset, or there's a misunderstanding. Please answer these questions from my last message to help clear this up: Why are you unable to insert the actual, encoded characters into the text? What *are* you able to insert? What encoding are your files using? What platform (OS, editor, etc.)? It could be that you *can* insert real characters but don't know it.
But the substitution table using "proper" characters is good enough, although I'm not entirely sure that all backends output will be able to deal with two-byte Unicode.
HTML can handle UTF-8. XML uses Unicode internally and assumes UTF-8 or UTF-16 unless told otherwise. As for back-ends, that's a Writer issue. If output format X can't handle Unicode, then the X format's Writer needs to encode those characters or signal an error. TeX can't handle the &#xNNNN; form. Here's an alternative for you. If you want to use &whatever; XML character entities in your source, just put a simple filter into your tool chain that converts those entities into UTF-8. Something like:: charents2utf8 input.txt | docutils/tools/html.py > output.html There must be filters like that "out there". If not, it wouldn't be hard to write one, I think. A codec would do just as well, but Python doesn't come with such a codec (more's the pity). I just realized the front-ends don't have support for explicit stdin/stdout with "-" arguments. I'll add that soon. [re: interpreted text roles]
There's absolutely no need for any regex substitution here. That's exactly what the Writers are for. The ":gui:`File`" input may become "<gui>File</gui>" in the internal document tree. The HTML Writer would write it with bold (or, better yet, with <span class="gui">, made bold by the stylesheet). The DocBook Writer would write it with <guilabel>.
The problem with implementing it as a Writer is that Writers don't travel with the source text files. If I send you a ReST file with :gui: roles in it, what's your DocUtils installation going to do with it?
The set of roles built into Docutils itself will grow. If the growth proves to be unlimited or unmanageable, there will have to be an alternative. If those roles are not handled by the default Docutils set, then they can be local to your installation. They wouldn't be portable, true; there's only so far a "standard" can go and we can't please everybody 100%. There's also this alternative:
There has been some discussion about parameterizing the interpreted text system somehow, to avoid proliferation of element types (gui, keypress, etc.). No decision or action yet.
See the Doc-SIG thread, "master plan for interpreted text?" from last month.
If "parameterizing the interpreted text system" means that simple role substitutions -- the kind that can be handled by regex -- can be placed within the source text files, great! It makes the source text more portable.
But I doubt it will take the form of "regex substitutions". That's just too low-level, IMHO.
If the role can't be handled by a regex, then of course it's going to require a Writer. (Although... if one could embed a Python script... but, no. That's verging on silly.)
Have you read PEP 256 & 258 yet? Please do. They explain the Docutils architecture and the purpose of the components (Writer, Reader, Parser, etc.).
And if this email has been scrunched into a blob, I apologize.
Try leaving a space on each blank line. I.e., [return] [space] [return]. I've done that just above. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
On Sat, 15 Mar 2003 10:55:09 -0500, David Goodger <goodger@python.org> wrote:
The '&' entity is used by HTML and XML to represent the '&' character.
I shouldn't have to use inline literals here.
Personal preference, I suppose. I'm already used to "escaping" entities when I'm writing about them directly, so I've no problem with the idea that I can't just write & willy-nilly through my document and expect it to display as such.
Why are you unable to insert the actual, encoded characters into the text? What *are* you able to insert? What encoding are your files using? What platform (OS, editor, etc.)? It could be that you *can* insert real characters but don't know it.
*I* am able to insert the actual encoded characters into the text. There's no guarantee, however, that *others* are going to be able to see them. These docs are going to be edited on Windows, Mac, Linux, and BeOS boxes using whatever flavour of editor the end-user wants to use. That's why we have charents in the first place: it lets anyone, using any old editor on any old OS, and print the raw document on any printer -- even an old 1978 daisywheel wordwhacker.
[re: interpreted text roles]
The problem with implementing it as a Writer is that Writers don't travel with the source text files. If I send you a ReST file with :gui: roles in it, what's your DocUtils installation going to do with it?
The set of roles built into Docutils itself will grow. If the growth proves to be unlimited or unmanageable, there will have to be an alternative. If those roles are not handled by the default Docutils set, then they can be local to your installation. They wouldn't be portable, true; there's only so far a "standard" can go and we can't please everybody 100%.
I think that ReST has the opportunity to become a dominant markup standard. I've suggested to Opera that they make it their standard for email markup, as HTML email is a sin against humanity. The WikiWorld would do well to standardize on a single markup: it's very confusing to have to remember subtly different markups between various wikis. The ASCIIDoc author used his ST markup to create his website, and I've pointed him toward ReST as a direction for his ST project. And I'm intent on using ReST for my technical documentation. In the technical writing world DocBook is often overkill, especially when attempting collaborative work with naive users. The XML is complex, virtually requiring a DTD-aware editor, and patient study of the spec. ReST is nearly a perfect solution: it's intuitive, simple, and can be written using even a PDA. I hope I'm coming at this from a different angle than the rest of you, because that way I'll be able to contribute another view on how ReST can be used to best effect. I think one of the best ways to encourage wide adoptation is to make it as easy as possible for functionality to be implemented within the source text files. It's going to be next to impossible to keep up with everyone's various ideas for roles. The more that a role's functionality can be put into a text sourcefile, the easier it is to share one's documents.
On Sat, Mar 15, 2003, David Priest wrote:
I hope I'm coming at this from a different angle than the rest of you, because that way I'll be able to contribute another view on how ReST can be used to best effect.
No, your attitude is similar to mine, but it sounds like you've got a lot more experience as a tech writer with which to express your opinion. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Register for PyCon now! http://www.python.org/pycon/reg.html
On Sat, 15 Mar 2003 19:26:19 -0500, Aahz <aahz@pythoncraft.com> wrote:
On Sat, Mar 15, 2003, David Priest wrote:
I hope I'm coming at this from a different angle than the rest of you, because that way I'll be able to contribute another view on how ReST can be used to best effect.
No, your attitude is similar to mine, but it sounds like you've got a lot more experience as a tech writer with which to express your opinion.
Experience writing end-user docs for hardware and software, not experience in writing docs for APIs, PEPs, and the like.
[David Goodger]
The '&' entity is used by HTML and XML to represent the '&' character.
I shouldn't have to use inline literals here.
[David Priest]
Personal preference, I suppose.
It's practicality. In many of my documents, I (and, I imagine, other authors) write *about* <tags> and &entities; and other uses of these characters. Some people write "&c" instead of "etc". Should the parser generate an error for this? I think not.
Why are you unable to insert the actual, encoded characters into the text? What *are* you able to insert? What encoding are your files using? What platform (OS, editor, etc.)? It could be that you *can* insert real characters but don't know it.
*I* am able to insert the actual encoded characters into the text. There's no guarantee, however, that *others* are going to be able to see them. These docs are going to be edited on Windows, Mac, Linux, and BeOS boxes using whatever flavour of editor the end-user wants to use.
So ASCII is your lowest common denominator? I sympathize, but maintain that Docutils doesn't need a character entity subsystem. Your idea of a substitution table file will work fine, and since *you* have control of it, encoding it as UTF-8 shouldn't be a problem (and you can treat everything else as UTF-8 since it's a strict superset of 7-bit ASCII). Just change the table from this form:: .. exclamation point: .. |excl| replace:: ! to this form:: .. exclamation point: .. |excl| replace:: ! I.e., use the concrete characters. I just realized there's a problem: reStructuredText is case-insensitive, so É and é will clobber each other. You'll either have to come up with a different name scheme, or perhaps the parser can be changed to be case-sensitive-but-forgiving for substitution names. I think that change is feasible, but I haven't thought through the consequences.
I hope I'm coming at this from a different angle than the rest of you, because that way I'll be able to contribute another view on how ReST can be used to best effect.
Your contributions are most welcome. Just don't expect every idea to be adopted. :-)
I think one of the best ways to encourage wide adoptation is to make it as easy as possible for functionality to be implemented within the source text files.
I'm very leery of making reStructuredText into a programming language or meta-markup language. Simplicity is one of its strengths, and the existing extension mechanisms (directives, interpreted text roles, substitutions) are already more than complex enough.
It's going to be next to impossible to keep up with everyone's various ideas for roles.
Perhaps. But I'm not going to implement a solution until it's the *right* solution. Regexes ain't it, sorry :-).
The more that a role's functionality can be put into a text sourcefile, the easier it is to share one's documents.
I'd rather put the functionality into Docutils itself. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
On Sat David Goodger <goodger@python.org> wrote:
Some people write "&c" instead of "etc". Should the parser generate an error for this? I think not.
Just a quick note: &c doesn't fall into the charent pattern. So we're down to inconviencing one of two groups. In group one, those who are writing anything involving extended characters (ie. mathematics, physics, papers with the occasional foreign word) will need to consult a lookup table to figure out what ALT+keypad combination will create the character they want, and will not be able to use just any old editor; but those writing about XML and such will be able to refer to charents without having to use ``&name;`` escaping. In group two, those writing about XML and such will have to use ``&name;`` escaping, but everyone else will be able to use charents to insert the occassional extended character into their work and use any editor they care to use. I know which group I want to belong to, but then I don't spend a lot of time writing about charents. But it doesn't really matter: I can get the substitution table to work, so the problem is resolved. Much to your relief, I'll drop the matter now.
On Sat David Goodger <goodger@python.org> wrote:
Some people write "&c" instead of "etc". Should the parser generate an error for this? I think not.
David Priest wrote:
Just a quick note: &c doesn't fall into the charent pattern.
It does if followed by a semicolon. Splitting hairs can be dangerous; may result in a chain reaction.
Much to your relief, I'll drop the matter now.
Good. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
The following replacement code allows HTML4css1.py to support the use of charents. It can be easily adapted to the other writers, I'm sure. def encode(self, text): """Encode special characters in `text` & return.""" # @@@ A codec to do these and all other HTML entities would be nice. # text = text.replace("&", "&") # match standard charent forms (&NUM; &xHEXNUM; and &namedEntity;) text = re.sub(r'&(?!(([a-zA-Z]{2,};)|(#(x|X)?[0-9a-fA-F]{2,4};)))', r'&', text) text = text.replace("<", "<") text = text.replace('"', """) text = text.replace(">", ">") text = text.replace("@", "@") # may thwart some address harvesters return text
David Priest wrote:
The following replacement code allows HTML4css1.py to support the use of charents.
Unfortunately this code has a fatal side-effect. The HTML Writer runs all text is run throught the HTMLTranslator.encode method, even that of inline literals (<literal>) and literal blocks. Ignoring XML-style character entities ("&example;") would make it impossible to even *discuss* such entities in documents without jumping through hoops; not even ``&this;`` would be immune from being ignored. The addition of character-level inline markup support to the parser should enable you to implement the substitution table file scheme we discussed earlier. -- David Goodger http://starship.python.net/~goodger Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv
On Sat, 15 Mar 2003, David Priest wrote:
I think one of the best ways to encourage wide adoptation is to make it as easy as possible for functionality to be implemented within the source text files. It's going to be next to impossible to keep up with everyone's various ideas for roles. The more that a role's functionality can be put into a text sourcefile, the easier it is to share one's documents.
BUT: this needs to thought out very well, because he more functionality is in the source text, the more problems might arise having compatibility issues. and of course this might interfere with separation of content and format. OTOH: much might be done by preprocessor postprocessor and plugins. * a preprocessor simply fixes some special constructs and emits reST. if this is successful it might become a new reader. * postprocessing is similar but specialiced to the writer the preceeds it. on success make it a writer (option). * a plugin might be considered an external transform: might be done by two stage docutils: 1. reST to xml (or even the pickled internal data) 2. custom xml processing 3. xml to whatever writer might fit. on success becomes a transform ? -- BINGO: Wie gehts Ihnen mit ...? --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+
<grubert@users.sourceforge.net> wrote:
OTOH: much might be done by preprocessor postprocessor and plugins. * a preprocessor simply fixes some special constructs and emits reST. if this is successful it might become a new reader. * postprocessing is similar but specialiced to the writer the preceeds it. on success make it a writer (option). * a plugin might be considered an external transform: might be done by two stage docutils:
It's worth checking out ASCIIDoc. It was within a hair of being just enough functionality to allow me to do my technical publications with it. If it had had tables support, I probably would have stopped my search there. ASCIIDoc uses a config file to move some simple functionality out of the program, but at the same time keep it out of the source text files. This includes substitutions (word, character, and tag) and regex macros. It was the regex macro capability that made it possible to arbitrarily extend ASCIIDoc for my needs, without modifying the application installation. Anyway, I think Steve's ASCIIDoc has some ideas worth stealing. I especially like his comments, sidebars, and boxes markup. Most intuitive.
participants (4)
-
Aahz -
David Goodger -
David Priest -
grubert＠users.sourceforge.net