Re: Project Start: Section 1

Luke Palmer <[email protected]> writes:

>> Mailing-List: contact [email protected]; run by ezmlm
>> Date: Sun, 10 Nov 2002 11:44:43 -0800
>> From: Michael Lazzaro <[email protected]>
>>
>> Determine a schema describing the fields/elements of the documentation,
>> in order for the docs to be databased & later sliced in a variety of
>> ways (beginner manual, advanced specs, test cases, etc.)  Input and/or
>> output requirements are, at minimum:
>> 
>>         -- as XML
>>         -- as HTML
>>         -- as manpage (*roff)
>>         -- as PDF
>>         -- as LaTex
>>         -- as POD
>>         -- as executable test cases
>> 
>> Note that POD consists of formatting directives, not schema information,
>> and so cannot represent the information in a form sufficient for full
>> slicing.  At this point it would therefore appear that XML is the most
>> obvious authoring option.
>
> I very much dislike XML for writing.  

Agreed.

> It'd be nice to use some kind of "extended POD" or something.
> Something that's mostly content, little structure.  

=begin doc-schema

<perldoc-schema>...</perldoc-schema>

=end doc-schema

> Of course, a sensible XML format could still be useful.  Very
> sensible.

Representing document metatdata in XML makes a good deal of sense; but
with only a very small amount of thought that can be inlined in POD
documentation. 

-- 
Piers

   "It is a truth universally acknowledged that a language in
    possession of a rich syntax must be in need of a rewrite."
         -- Jane Austen?