[work] Re: [Doc-SIG] Hello and feedback

[David Priest]

On Sat, 15 Mar 2003 10:55:09 -0500, David Goodger <goodger@python.org> 
wrote:
> The '&amp;' 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 &amp; 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.