SEUL: SDOC work to be done

[Erik Walthinsen <omega@omegacs.net>]

We need to do some major work on sdoc.  What we have works, but barely.  
It's not very extensible, at least not without some major work.  I would like
to get together a group of 3 or 4 people from this group, and elsewhere if
possible/necessary, to discuss, develop, and maintain sdoc.

Currently, there are several problems with sdoc itself that need to be 
fixed:

1) it's slow.  Can be fixed by removing some recursion (there is lots), 
redefining the handler interface to use perl modules (it recompiles the 
handlers on *every* invocation right now), and probably some other less 
obvious things

2) the parsing is touchy.  There are other bits of perl out there 
(HTML::Parser, for instance) that might be used to gain efficiency as well 
as cleaner code.  Then again, maybe not.

3) it assumes it's working in a vacuum.  That makes creating 
filesystem-specific hooks in handlers difficult.  This is really a trivial 
fix in the code one way or another, once we determine how we want to do it. 
Primary issue is how sdoc knows about the file and its location.

4) new features:
   a) handlerstacks: when a handler is installed, it would sit on top of 
the stack.  When it knows it's done with all its work, it removes itself 
from the stack for that tag.  If there's something underneath it, that 
continues and does something else.
   b) new completion code: if we have handlerstacks, we can define 
completion more generally as whenever all the handlerstacks are empty, we 
can avoid some duplication in the handlers, as we would no longer have to 
not only remove ourselves from the stack, but indicate via return code that 
we don't need to run again.  Kinda redundant.
   c) new hooks: There should be a few more hooks in various places, like 
before and after each pass, etc.  They should all use the same mechanism 
developed for module-based handlers with handlerstacks.  Stacks are good.


Then there are the handlers:

1) they don't co-exist very well at all.  Since we don't have handlerstacks
yet, one handler will overwrite another, which can produce ugly results in
some cases where one tag relies on another.  handlerstacks and some protocols
will solve that.

2) namespaces: when the calling mechanism is changed for handlers to 
module-based, decent namespaces will be enforced.  However, there will 
still be the issue of cross-handler and cross-doctype communication.  I 
suppose if we develop a decent hierarchy, something like
SDOC::doctype::<doctyype>::<handler>, we'll just be able to shove variables
on one or three levels to get the appropriate context.

3) interoperability: The idea behind sdoc is to be able to provide extra 
levels of site design without having to make the source document ugly.  
That implies that creating a new look&feel for a site should be reasonably 
easy.  The problem is that right now it's not.  If you want a new look and 
feel, you have to build it up from scratch.

What we need to have is the ability to include common functions, like the 
section tags and TOC, as part of a larger doctype.  Since section and TOC 
tags are so common, they will have to be *very* generic, and be capable of 
hooks of their own for doctypes to latch into.  With proper namespaces, 
this is a lot easier, but still has to be done very carefully.  It should 
be configurable enough so that the same tags can be capable of FAQ-style 
formatting and hrefs, which currently is a separate set of handlers 
entirely.


I would like to get some discussion going really soon, starting with ideas, 
then someone needs to go over what we have and document it.  Then plans can 
be drawn up, and we can build everything.  This needs to happen RSN, as 
there are several people waiting for some of these things in order to create
sites (linuxunited, twoducks' dev-help site, etc.).  I'll be representing 
SEUL, linuxunited, and some of my own ideas relative to a site I'm going to 
be designing for my dad's business.

People who I know will be involved at this point: omega (me, wrote all the 
handler code), arma (wrote the sdoc parser core), swaldman (webmaster for
seul.org), lohner (working on linuxunited stuff), twoducks (seul-dev-help
project leader).  Anyone working on actually coding stuff will need a 
fairly solid grounding in Perl, and some experience with parser stuff would 
be handy.  Just playing around and building a doctype of complexity similar 
to the section/toc handlers would work.

TTYL,
    Omega


     Erik Walthinsen <omega@seul.org> - SEUL Project system architect
        __
       /  \                SEUL: Simple End-User Linux -
      |    | M E G A            Creating a Linux distribution
      _\  /_                         for the home or office user