base format for zsh documentation

[Richard Coleman <coleman@xxxxxxxxxxxxxxx>]

I've looked at various ways to handle documentation for zsh.
I've looked at pod, sgml, and other formats, but was never completely
happy.  Here's a new possibility.  Anyone have any experience with
this program?

rc

---------------------------------------------------------------------------
Here's the LSM entry:

Begin3
Title:          YODL: Yet Oneother Document Language
Version:        1.07
Entered-date:   1996
Description:    YODL is a package that implements a pre-document language and
                tools to process it. The idea of YODL is that you write up a
                document in a pre-language, then use the tools (eg.
                yodl2html) to convert it to some final document language.
                Current converters are for HTML, man and LaTeX, plus a
                poor-man's ASCII converter. Main document types are "article",
                "report", "book" and "manpage".  The YODL document language is
                designed to be easy to use and extensible.
Keywords:       document language converter
Author:         karel@xxxxxxxxxxx (Karel Kubat)
Maintained-by:  karel@xxxxxxxxxxx (Karel Kubat)
Primary-site:   ftp.icce.rug.nl:/pub/unix, file:yodl-1.07.tar.gz
Alternate-site: sunsite.unc.edu: no idea where
		tsx-11.mit.edu:  no idea where
Copying-policy: PostcardWare (if you like it, send me a postcard)
		MegaHard (who wants a picosoft)
		but really: GPL
End


And for your enjoyment, here's the Readme:

notableofcontents()
article(YODL - or, Yet Oneother Document Language)
       (Karel Kubat tt(karel@xxxxxxxxxxx))
       (1996)

    quote(This file double-serves as the announcement that goes to
    em(comp.os.linux.announce), and as a message to the maintainers of
    em(sunsite.unc.edu) and em(tsx-11.mit.edu). So it's a slightly unpersonal
    message... sorry 'bout that.

    What's more, this message is in the YODL document language. What better
    way to demonstrate? If you see a lot of parentheses, just read over them.
    This file in `source' format should be readable nevertheless.)

nsect(What's YODL?)

    YODL (Yet Oneother Document Language) is a package that consists of
    programs, some shell scripts, and auxiliary "lib" files for which hold
    macro files. The whole purpose of the package is to provide a
    simple-to-use and extensible document language, that can be used to
    convert documents in the YODL format to a variety of other formats. In
    this purpose, YODL somewhat resembles generic markup languages, e.g. SGML
    footnote(Standard Generalized Markup Language) but:

    nsubsect(How easy to use is it?)

	YODL is easier to use. Well I find so. Typing parentheses is I think
	less work than typing <> or \{}.

    nsubsect(How good is the documentation?)
    
	YODL is very well documented. That my version of SGML isn't is, I
	guess, no fault of SGML, but I had a bf(very) hard time getting SGML
	to do what I wanted it to do! Well, YODL should be easier to handle.
	The docs include various manpages and a full document of approximately
	60 DIN A4 pages. (If you don't like DIN A4, just make your own
	reference docs! The sources for the document, of course in YODL
	format, are included.)

    nsubsect(Does it use tags?)
    
	YODL doesn't insist on weird tags. YODL is not a markup language in
	that sense (starting and ending tags), YODL handles all its commands
	in a C-style manner; e.g. tt(em(...)) will set the text emphasized.
	Similarly, macros can have two arguments or more, also all in a
	parameter-list format. This is more of an advantage than you might
	think at first glance:  e.g., my editor won't match a closing tag in
	HTML with the opening tag, but it bf(will) show the open-parenthesis
	when I type a closing parenthesis!

    nsubsect(Does it have conditional parsing?)
    
	YODL has support for conditional processing: by testing for some
	symbol, or say for the presence of an argument, you can do different
	things in a macro. Or you can redefine macros, and the such.

    nsubsect(What can it do?)

	Currently the package supports conversions to LaTeX, HTML, to the
	"man" format, to the "ms" format, and poor-mans conversions to plain
	ASCII and SGML (for compatibility reasons at our site).  Other
	conversions are of course possible, but these are the formats that I
	use and hence the converters that I put some effort into.

nsect(Where to get it?)

    If you want to obtain YODL and try it out, ftp to
    ftp://ftp.icce.rug.nl/pub/unix/ and look for a file yodl-X.YY.tar.gz, with
    X.YY being a version number (0.00 is of course the first). The YODL 
    distribution is also on the `standard' Linux sites.
    
    Unpack it in a "sources" directory and type "make htmldoc" or "make 
    latexdoc" and see for yourself...

nsect(Last remarks)

    YODL has evolved from the previous DOM package, that I developed but
    didn't distribute yet. DOM used to be "DOcument Maintainer", but I don't
    think that the nomenclature was too good. (Besides, I can now use ".yo"
    for file extensions ;-)

    YODL is currently beta-state, that means that it may not be very complete
    (but I'm working on it), that there may be bugs in it (not that I know
    of), and that new versions may arrive quickly.  Yes, I am looking for
    testers! If you're interested, get YODL and mail me what you think.

    Just for fun, at the end the same document is included, but converted to
    plain ASCII via the "groff -ms" route. Well, that's all, I hope that I've
    tickled your curiosity!

    Karel.











         YODL - or, Yet Oneother Document Language

               Karel Kubat karel@xxxxxxxxxxx
                            1996



     This  file  double-serves as the announcement that goes
     to comp.os.linux.announce, and  as  a  message  to  the
     maintainers  of  sunsite.unc.edu and tsx-11.mit.edu. So
     it's a slightly unpersonal message... sorry 'bout that.

     What's  more, this message is in the YODL document lan-
     guage. What better way to demonstrate? If you see a lot
     of  parentheses,  just  read  over  them.  This file in
     `source' format should be readable nevertheless.



What's YODL?


     YODL (Yet Oneother Document Language) is a package that
     consists of programs, some shell scripts, and auxiliary
     "lib" files for which hold macro files. The whole  pur-
     pose  of  the package is to provide a simple-to-use and
     extensible document language, that can be used to  con-
     vert documents in the YODL format to a variety of other
     formats.  In  this  purpose,  YODL  somewhat  resembles
     generic markup languages, e.g. SGML [1] but:


How easy to use is it?


     YODL is easier to use. Well I find so. Typing parenthe-
     ses is I think less work than typing <> or \{}.


How good is the documentation?


     YODL is very well documented. That my version  of  SGML
     isn't  is,  I guess, no fault of SGML, but I had a very
     hard time getting SGML to do what I wanted  it  to  do!
     Well,  YODL  should  be  easier  to  handle.   The docs
     include various manpages and a full document of approx-
     imately  60  DIN  A4  pages. (If you don't like DIN A4,
     just make your own reference docs! The sources for  the
- -----------
[1] Standard Generalized Markup Language


                             -2-


     document, of course in YODL format, are included.)


Does it use tags?


     YODL doesn't insist on weird tags. YODL is not a markup
     language in that sense (starting and ending tags), YODL
     handles  all  its  commands  in  a C-style manner; e.g.
     em(...)  will  set  the  text  emphasized.   Similarly,
     macros  can  have  two arguments or more, also all in a
     parameter-list format. This is  more  of  an  advantage
     than  you might think at first glance:  e.g., my editor
     won't match a closing tag in HTML with the opening tag,
     but  it  will  show  the open-parenthesis when I type a
     closing parenthesis!


Does it have conditional parsing?


     YODL has support for conditional processing: by testing
     for  some  symbol,  or say for the presence of an argu-
     ment, you can do different things in a  macro.  Or  you
     can redefine macros, and the such.


What can it do?


     Currently  the  package  supports conversions to LaTeX,
     HTML, to the "man" format,  to  the  "ms"  format,  and
     poor-mans conversions to plain ASCII and SGML (for com-
     patibility reasons at our site).  Other conversions are
     of  course  possible,  but these are the formats that I
     use and hence the converters that  I  put  some  effort
     into.


Where to get it?


     If  you  want  to  obtain  YODL  and try it out, ftp to
     ftp://ftp.icce.rug.nl/pub/unix/ and  look  for  a  file
     yodl-X.YY.tar.gz,  with  X.YY  being  a  version number
     (0.00 is of course the first). The YODL distribution is
     also on the `standard' Linux sites.

     Unpack it in a "sources" directory and type "make html-
     doc" or "make latexdoc" and see for yourself...


                             -3-


Last remarks


     YODL has evolved from the previous DOM package, that  I
     developed  but  didn't  distribute  yet. DOM used to be
     "DOcument Maintainer",  but  I  don't  think  that  the
     nomenclature  was  too  good.  (Besides,  I can now use
     ".yo" for file extensions ;-)

     YODL is currently beta-state, that means  that  it  may
     not  be  very  complete  (but  I'm working on it), that
     there may be bugs in it (not that I know of), and  that
     new versions may arrive quickly.  Yes, I am looking for
     testers! If you're interested, get  YODL  and  mail  me
     what you think.

     Just for fun, at the end the same document is included,
     but converted to plain ASCII via the "groff -ms" route.
     Well, that's all, I hope that I've tickled your curios-
     ity!

     Karel.

- --
Karel Kubat (karel@xxxxxxxxxxx, karel@xxxxxxxxxxxxxxxxxx).
>From the "Top 25 Explanations by Programmers:"
#8: The user has made an error again.