[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 language because inevitably some tools (e.g. emacs psgml,
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 extra layers 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. This
"flexibility" leads to an infinite number of contrived, incompatible
languages. So yes, I would rather byte the bullet and use SGML in this
way than invent Yet Another Markup Language (what are we up to, 30, 40
of them?).

 Paul Prescod

_______________
DOC-SIG  - SIG for the Python Documentation Project

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