From: David P. <pr...@sf...> - 2003-07-21 19:14:54
|
It's been a while since I posted, so let me state my background again: I'm writing user manuals for some hardware/software products. These manuals were previously created using Ventura Publisher, which is a long-document application rather like Framemaker (but with a far better UI). I have completed a fifty-odd page hardware reference manual and am in the process of finishing a two-hundred-odd page software reference manual. These manuals are published to PDF through DocUtils XML and a set of XSL:FO transformations that I have written over the past two months. The Apache FOP renderer is used to publish XML:FO to PDF. I would like to share the XML:FO transformation sheets with DocUtils users. I believe I shall generally do this by writing a web tutorial, so that users can customize the sheets as needed for their own particular application. I'll do this when I get a chance, probably starting in September. DocUtils has been mostly very good for my needs. I do, however, find that it has a few gaping holes that are very likely to pose a problem for most authors. These are as follows: - there is no support for UI element tagging. No :mouse:, :key:, or :gui: tags. This is a shame, because a lot of DocUtil authors are, I believe, documenting software, which generally means they're documenting user interfaces. - targets are sometimes mis-located. In particular, placing a target before a section header puts the target at the end of the previous section instead of the start of the next section. Programatically this makes sense; aesthetically, it does not: one usually places a target reference immediately before the thing being targeted. This probably merits some amount of discussion. - we could use a .. comment:: [author] tag. This would facilitate team authoring. There are ordinary comments, but these are prey to misidentification, and there's no way to automagically pull them from the source by author name. Indeed, a kick-ass comment tag would allow for author, date, and ID. If you're interested in the XSL:FO stuff, give a shout. I'm happy to share, provided you feedback your changes or ideas to me. When I write the tutorial, I'd like the XSL:FO to be maximally useful to the broadest number of users. |
From: Adam C. <ad...@ch...> - 2003-07-22 13:07:46
|
On Mon, 21 Jul 2003 12:14:25 -0700 "David Priest" <pr...@sf...> wrote: [...] > If you're interested in the XSL:FO stuff, give a shout. I'm happy to > share, provided you feedback your changes or ideas to me. When I > write the tutorial, I'd like the XSL:FO to be maximally useful to the > broadest number of users. /me shouts :-) -- Adam Chodorowski <ad...@ch...> Join the Army, meet interesting people, kill them. |
From: David G. <go...@py...> - 2003-07-29 05:21:52
|
David Priest wrote: > It's been a while since I posted, Welcome back! Did you know about <http://docutils.sourceforge.net/tmp/charents/>? Another of your ideas, about character processing with regexps, has also been discussed recently ("automatic typography" thread on docutils-users) and is partially summarized at <http://docutils.sf.net/spec/rst/alternatives.html#character-processing>. > I would like to share the XML:FO transformation sheets with DocUtils > users. I believe I shall generally do this by writing a web > tutorial, so that users can customize the sheets as needed for their > own particular application. I'll do this when I get a chance, > probably starting in September. You're welcome (and encouraged!) to put files in a sandbox directory before then, in case they'd be of use to anyone. Send me your SourceForge user ID and I'll add you as a developer. > - there is no support for UI element tagging. No :mouse:, :key:, or > :gui: tags. This is a shame, because a lot of DocUtil authors are, > I believe, documenting software, which generally means they're > documenting user interfaces. What might be the best solution is outlined in the proposal at <http://docutils.sf.net/spec/notes.html#role-bindings>. We've discussed these before, most recently on the Doc-SIG list in June. There hasn't been any implementation progress since. > - targets are sometimes mis-located. In particular, placing a > target before a section header puts the target at the end of the > previous section instead of the start of the next section. > Programatically this makes sense; aesthetically, it does not: one > usually places a target reference immediately before the thing being > targeted. This probably merits some amount of discussion. This could and should be fixed. There's already code that does a similar job of repositioning, for the "class" directive. I added this to the bugs list (higher priority than to-do). > - we could use a .. comment:: [author] tag. This would facilitate > team authoring. I don't see why a directive would be required. You could just standardize on an appropriate comment format for your group, like:: .. [author/2003-07-29/ID] Comment text here... > There are ordinary comments, but these are prey to > misidentification, and there's no way to automagically pull them > from the source by author name. Indeed, a kick-ass comment tag > would allow for author, date, and ID. I would think that such a system would be very author/group-specific, and any extraction mechanism would have to be a separate tool. A simple filter could be written to locate, analyze, and report comments matching a certain pattern. Comments are kept in the internal document tree after parsing; an extraction tool could use Docutils to parse the input file and extract comments from the doctree. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |
From: David P. <pr...@sf...> - 2003-07-29 15:38:21
|
On 29 Jul 2003 at 1:20, David Goodger wrote: > David Priest wrote: > > It's been a while since I posted, > > Welcome back! Did you know about > <http://docutils.sourceforge.net/tmp/charents/>? Yes, and I'm actively using it. It's great! > Another of your > ideas, about character processing with regexps, has also been > discussed recently ("automatic typography" thread on docutils-users) > and is partially summarized at > <http://docutils.sf.net/spec/rst/alternatives.html#character-processin > g>. Sweet. I'd like to have automatic typography, and there's one word that's used frequently which needs special formatting. I tried using a substitution, but it didn't seem to work. (The word is "Matrix3", and the "3" needs to be superscripted. Actually, it needs to be typeset a little differently that superscript, but I'm willing to do the superscript-mangling in the XML:FO part of the workflow.) > > I would like to share the XML:FO transformation sheets with > DocUtils > users. I believe I shall generally do this by writing a > web > tutorial, so that users can customize the sheets as needed for > their > own particular application. I'll do this when I get a > chance, > probably starting in September. > > You're welcome (and encouraged!) to put files in a sandbox directory > before then, in case they'd be of use to anyone. Send me your > SourceForge user ID and I'll add you as a developer. Will do come September. I'm heading hols this week. > > - there is no support for UI element tagging. No :mouse:, :key:, > or > :gui: tags. This is a shame, because a lot of DocUtil authors > are, > I believe, documenting software, which generally means they're > > documenting user interfaces. > > What might be the best solution is outlined in the proposal at > <http://docutils.sf.net/spec/notes.html#role-bindings>. We've > discussed these before, most recently on the Doc-SIG list in June. > There hasn't been any implementation progress since. 'k. > > - targets are sometimes mis-located. In particular, placing a > > target before a section header puts the target at the end of the > > previous section instead of the start of the next section. > > Programatically this makes sense; aesthetically, it does not: one > > usually places a target reference immediately before the thing being > > targeted. This probably merits some amount of discussion. > > This could and should be fixed. There's already code that does a > similar job of repositioning, for the "class" directive. I added this > to the bugs list (higher priority than to-do). I dealt with this using some major juju in the XML:FO transformation. It isn't thoroughly tested, and is specific to only section titles. Thanks for the info et al, (another) david |
From: David G. <go...@py...> - 2003-08-03 18:56:16
|
David Priest wrote: > there's one word that's used frequently which needs special > formatting. I tried using a substitution, but it didn't seem to > work. > > (The word is "Matrix3", and the "3" needs to be superscripted. This should do it: Matrix\ :sup:`3` You can put that in a "replace" substitution if you like. -- David Goodger |
From: David P. <pr...@sf...> - 2003-08-29 05:05:09
|
> > - we could use a .. comment:: [author] tag. This would facilitate > > team authoring. > > I don't see why a directive would be required. You could just > standardize on an appropriate comment format for your group I note that you've used the ``.. @@@`` convention. I think I'll use ``.. @[initials]``. Feel free to formalize this convention (yielding, I suppose, something like :: <comment xml:space="preserve"> <author>DCP <paragraph>stuff <paragraph>stuff The @ sign even reads a little like "@uthor". On the other hand, I could now just check if the first paragraph starts with an @, and handle appropriately if it is. :-) I've just taken a look at the ``notes.txt`` file regarding role- binding. I particularly like the ideas of substituting directives for roles :: `She wore ribbons in her hair and it lay with streaks of grey`:rewrite: .. :rewrite: class:: rewrite This would essentially resolve all the problems I've been having marking-up various GUI elements in my documentation (menu command- chains, keyboard shortcuts, mouse actions, etcetera). It would, in short, be a godsend. Or at least a goodgersend. Regarding the ``notes.txt`` file, lines 1500ish, about acronyms: "What to do if there are multiple definitions? How to differentiate between CSS (Content Scrambling System) and CSS (Cascading Style Sheets) in a single document?" The short answer is: you don't. Anyone who did such a thing would be writing very poor documentation indeed. (Though I note that somewhere else in the docs, there's mention of allowing replacement text to be associated with the abbreviation. That takes care of the duplicate acronyms/abbreviations problem, though a writer would be foolish to ever need it.) |
From: David G. <go...@py...> - 2003-08-29 13:50:27
|
David Priest wrote: >>> - we could use a .. comment:: [author] tag. This would facilitate >>> team authoring. >> >> I don't see why a directive would be required. You could just >> standardize on an appropriate comment format for your group > > I note that you've used the ``.. @@@`` convention. I think I'll use > ``.. @[initials]``. Feel free to formalize this convention > (yielding, I suppose, something like :: > <comment xml:space="preserve"> > <author>DCP > <paragraph>stuff > <paragraph>stuff Problem here is, <comment> is a CDATA-content element (or it would be, if XML allowed it). IOW, there is no internal structure, no nested tags -- intentionally. It's just text. > The @ sign even reads a little like "@uthor". Yuck! :-) > On the other hand, I could now just check if the first paragraph > starts with an @, and handle appropriately if it is. :-) That's a better approach IMO. > I've just taken a look at the ``notes.txt`` file regarding role- > binding. I particularly like the ideas of substituting directives > for roles :: > `She wore ribbons in her hair and it lay with streaks of > grey`:rewrite: > .. :rewrite: class:: rewrite > > This would essentially resolve all the problems I've been having > marking-up various GUI elements in my documentation (menu command- > chains, keyboard shortcuts, mouse actions, etcetera). It would, in > short, be a godsend. Or at least a goodgersend. I can't think of any negative ramifications to the syntax/functionality proposal. Don't know when it'll be implemented though. > Regarding the ``notes.txt`` file, lines 1500ish, about acronyms: ... > The short answer is: you don't. ... I've noted your response in the notes.txt file, thanks. -- David Goodger http://starship.python.net/~goodger For hire: http://starship.python.net/~goodger/cv Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) |