[DOC-SIG] Library reference manual debate

[Case Roole]

Paul Prescod wrote:

> 
> Case Roole wrote:
> > Just wondering: for HTML generation I use "megatags", non-HTML tags in
> > documents that are otherwise HTML. An SGML parser (derived from the one
> > in sgmllib) lets pure HTML pass, but fetches and processes the data
> > embedded in these megatags (example below). This is decidedly not pure
> > SGML or pure HTML, but the *code is extremely readable*. Is this what
> > everybody is using the SGMLParser for, is it irrelevant for the matter
> > discussed here, or is this a good idea?
> 
> SGML was explicitly designed to allow this and has features to do this
> sort of thing for you. A full SGML parser can interpret your "=" symbol
> and even your newlines as tags. This is very convenient for typists. 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. Also to parse something
> like this in Python we would either have to complicate sgmllib or
> introduce another layer of parsing.

Shortly:
1. What's wrong with introducing another layer of parsing?
2. I have reason to doubt that a mixed format will be confusing.

Extended:

ad 1.)  I haven't looked at SGML for years and forgot much of what I once 
   learned. I take it on your word that a full SGML parser can interpret 
   all kinds of non '<'..'>' embedded tokens. If we are using a python 
   WYSIWYG editor based on a DTD for these docs, the proposed mixed format 
   would require a complication of sgmllib. 
   I have the impression that the consensus is that we are to use a 
   non-wysiwyg editor for the time being, so this doesn't apply. 
   Thus I end up with the other option, which, fortunately, is what I was 
   thinking of in the first place: introduce another layer of parsing.
   I can think of no other penalty for this than that the computer works
   a little longer when doing the one-time job of converting the dirty-
   but-readable manual format into something standard tools can further
   process.

ad 2.)   I doubt the validity of your assessment of the degree to which a
   mixed format is "confusing".

  "This is very convenient for typists." -- Indeed, that's what Guido was 
  referring to when he started this thread.

  "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". 
  We all get along with not closing python statements with ';' and not
  enclosing blocks in '{'..'}'. I guess that those who write the
  documentation will catch up quickly if the documentation is to be written
  in some mixed format that looks good, even if it would take an advanced
  SGML parser to interpret it in a single step.

cjr

-- 
Case Roole <cjr@bound.xs4all.nl>


_______________
DOC-SIG  - SIG for the Python Documentation Project

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