From: Dave Thomas <Dave@...>
Date: 2002-09-08T01:33:16+09:00
Subject: Re: Document tools

<bbense+comp.lang.ruby.Sep.07.02@telemark.stanford.edu> writes:

> It certainly is possible. POD shows us the way. I think the
>   point I'm trying to make is that POD is an output format.
>   It just happens to be so trivial that it's accepted in the
>   perl community to write raw POD. Once you have a well defined
>   simple output format, you can translate that to any other format 
>   required. 

Here's the start of perlpod.pod in pod format:

  =head1 NAME

  perlpod - plain old documentation

  =head1 DESCRIPTION

  A pod-to-whatever translator reads a pod file paragraph by paragraph,
  and translates it to the appropriate output format.  There are
  three kinds of paragraphs:
  L<verbatim|/"Verbatim Paragraph">,
  L<command|/"Command Paragraph">, and
  L<ordinary text|/"Ordinary Block of Text">.

  =head2 Verbatim Paragraph

  A verbatim paragraph, distinguished by being indented (that is,
  it starts with space or tab).  It should be reproduced exactly,
  with tabs assumed to be on 8-column boundaries.  There are no
  special formatting escapes, so you can't italicize or anything
  like that.  A \ means \, and nothing else.

  =head2 Command Paragraph

  All command paragraphs start with "=", followed by an
  identifier, followed by arbitrary text that the command can
  use however it pleases.  Currently recognized commands are

      =head1 heading
      =head2 heading
      =item text
      =over N
      =back
      =cut
      =pod
      =for X
      =begin X
      =end X

  =over 4

  =item =pod

  =item =cut

  The "=pod" directive does nothing beyond telling the compiler to lay
  off parsing code through the next "=cut".  It's useful for adding
  another paragraph to the doc if you're mixing up code and pod a lot.

  =item =head1

  =item =head2

  Head1 and head2 produce first and second level headings, with the text in
  the same paragraph as the "=headn" directive forming the heading description.


And here it is in RDoc:


  = NAME

  perlpod - plain old documentation

  = DESCRIPTION

  A pod-to-whatever translator reads a pod file paragraph by paragraph,
  and translates it to the appropriate output format.  There are
  three kinds of paragraphs: verbatim, command, and ordinary text. (RDoc
  doesn't yet support links to section heads. It's coming)

  == Verbatim Paragraph

  A verbatim paragraph, distinguished by being indented (that is,
  it starts with space or tab).  It should be reproduced exactly,
  with tabs assumed to be on 8-column boundaries.  There are no
  special formatting escapes, so you can't italicize or anything
  like that.  A \ means \, and nothing else.

  == Command Paragraph

  All command paragraphs start with "=", followed by an
  identifier, followed by arbitrary text that the command can
  use however it pleases.  Currently recognized commands are

      =head1 heading
      =head2 heading
      =item text
      =over N
      =back
      =cut
      =pod
      =for X
      =begin X
      =end X

  [=pod, =cut]
    The "=pod" directive does nothing beyond telling the compiler to lay
    off parsing code through the next "=cut".  It's useful for adding
    another paragraph to the doc if you're mixing up code and pod a lot.

  [=head1, =head2]
    Head1 and head2 produce first and second level headings, with the
    text in the same paragraph as the "=headn" directive forming the
    heading description.


Doesn't seem to be much difference in readability to me. Why would I
convert RDoc as an input format to POD as an output format. Wouldn't I
be better off adding the extra output processors that folks wanted?



Regards


Dave