Re: makedoc syntax (was Re: [AD] Screen destruction documentation update)

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sat, 2005-09-10 at 13:48 +1000, Peter Wang wrote:
> On 2005-09-10, Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx> wrote:
> > On 2005-09-09, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> > > Can we get rid of any ` at least for the new makedoc?
> 
> I think the textual parts of new makedoc documents should be strict XML,
> with no "enhancements".  You'd have to write <code>blah</code> or
> <tt>blah</tt> instead of `blah'.  We also would drop non-standard stuff
> like "&gt" without the semicolon, the automatic interpretation of "&" as
> "&amp;", missing closing tags, etc.

Sounds good. We could also allow wiki syntax like '''bold''' or *bold*.
The only criterion should be to make editing of the format for humans as
easy as possible. Machine processing would be done on the XML output.

> However, section headings and such would retain the @-stuff syntax, so
> makedoc format would become XML with @-stuff around to indicate the
> document structure.
> 
> Ok, that is a slight lie.  Compare the following two examples.  There
> are implicit <para>s in the first version compared with the second
> version.  We could also NOT have implicit <para>s, in which case you
> could really say that makedoc is a simple macro layer on top of XML.
> 

I think there should be implicit paras. As I said, everythng that makes
editing easier. Also, there should be word-wrapping - you can't really
expect documentation editors to count the letters in each line. So, yes,
a layer on top of XML, in the sense that you can hand-edit it. But no in
the sense that it would be very similiar to XML, which is un-editable.

Just my opinion of course.

-- 
Elias Pschernig