[DOC-SIG] Library reference manual debate

[Paul Prescod]

Case Roole wrote:
>   "I think that for novice users it will probably be quite confusing,
>   however, because people are used to all SGML markup being in clearly
>   marked tags, not in ordinary-looking characters." -- Given that we are
>   talking about the python documentation here, I don't see who those
>   "novice users" are, who are "used to all SGML markup being in clearly
>   marked tags".

Anybody familiar with HTML (in other words, almost everybody). 

I'm not dead-set against the idea. If it will help the SGML solution to
be more palatable, then let's do it. I just usually try to avoid
inventing my own delimiter language because inevitably some tools (e.g.
emacs psgml, perhaps FrameMaker+SGML) will not support it properly, and
I have to add more transformation layers to my publishing process. I
find that this is usually not worth the few keystrokes saved, but
intelligent people can differ on that issue. 

My biggest concern would be that these tool incompatibilities (or
partial compatibilitites) would be construed as "extra SGML
complications" whereas TIM, having no real popularity at all, can be
extended in an ad hoc manner and thus could be seen to be more
"flexible" than SGML. By that argument, a language I invent tomorrow
would be more "flexible" than Python because it has no installed base
and thus I can change it to be whatever I want, but lose the support of
a community and a set of existing tools. This "flexibility" leads to an
infinite number of contrived, incompatible languages. So yes, I would
rather byte the bullet and invent our own delimiter conventions within
SGML rather than invent Yet Another Markup Language. 

But just be aware that it will probably cost us in tool compatibility at
some point, and force us to do some extra transformations to a simpler
SGML subset.

 Paul Prescod

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________