[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

sdoc

> In fact, to enforce consistency in the look of the help system, some kind
> of text file "marked up" to the other formats would be better. For example
> :
> %TaskName 	Copy
> %TaskGroup	/KDE/file-management
> %Author		Donovan Rebbechi <elflord@pegasus.rutgers.edu>
> %Description	A tutorial on copying files in KDE
> %Steps
> %1	blah blah blah ... 
> 
> OK, I ripped this idea off the RPM spec file thing. The point is that html
> offers too much scope for the author to put in junk that's not needed or
> wanted, and it will take a more restrictive file format to be effective.
> This does not require much of the author, since some-one not familiar with
> the format can write one of these things by editing another one, since the
> format is very canned. 

This is why sdoc is so cool.  The handlers are written so that all these 
things appear in the source the same way, which itself is valid HTML for 
the most part.  Then the parser rewrites this into real HTML with 
whatever look you want:

<html>
<head>
<title>SEUL FAQ</title>
<meta name="doctype" content="webpage">
<meta name="handlerset" content="faq">
<meta name="author" content="mjackson">
<meta name="id" content="$Id: index.sdoc,v 1.2 1998/04/20 01:07:31 omega Exp $">
</head>
. . .

This will produce a document that has questions numbered, in sections, with 
a TOC and named links from one section to another (so you can arbitrarily 
rearrange things and the links stay valid).  When I'm done, it will list 
the author, have links for e-mail and web, it'll have a CVS revision string 
with a link to the cvsweb CGI showing the revision history, etc.  When I 
add some more features to the parser and handlers, you can change the META 
doctype to 'framedfaq' and get a framed version that's fully active on the 
server side, using ePerl.

Most of the documents on the SEUL website are done in sdoc (the exception 
being the main and dev homepages, because they're more complex).  To look 
at one, simply replace '.html' with '.sdoc' in the URL (add the index.html 
if necessary before you try it, of course :).

With some modifications, it could probably easily become a full SGML 
parser, thus handle linuxdoc-sgml and DocBook.  Depends on what we want to 
be doing.


     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