asciidoc: Re: [Swift-devel] A suggested web content strategy for Swift

[Michael Wilde]

And, in defense of docbook, there is "asciidoc" - like reStructured text but for docbook:

  http://www.methods.co.nz/asciidoc/index.html

and

  http://kaczanowscy.pl/tomek/2010-09/a-perfect-environment-for-docbook

The asciidoc user guide, presumably done using asciidoc, has some resemblance to our current User Guide:

  http://www.methods.co.nz/asciidoc/userguide.html

This might let us make a smoother evolution from our current docbook markup to a kinder gentler markup.

Justin, I am with you on deciding this soon. We may need some more experiments to do that.

- Mike


----- Original Message -----
> Yeah, that looks tedious. But there is also this form which works for
> most layouts:
> 
> Simple table:
> 
> ===== ===== ======
> Inputs Output
> ------------ ------
> A B A or B
> ===== ===== ======
> False False False
> True False True
> False True True
> True True True
> ===== ===== ======
> 
> I dont think tables will make or break it for us.
> 
> I like the simple style of most of the other text constructs.
> 
> - Mike
> 
> ----- Original Message -----
> > On Tue, 2011-03-01 at 11:54 -0600, Michael Wilde wrote:
> > >
> > > ----- Original Message -----
> > > > For what it's worth, I think that if folks don't want docbook
> > > > (which
> > > > I'd
> > > > more inclined to drop if there was any other reasonable
> > > > equivalent
> > > > system that produces good html output),
> > >
> > > Did you look at the reStructured text and Sphinx alternative I
> > > described, which is used by Python and many other projects?
> >
> > I believe that expressing tables like this:
> > +--------------+----------+-----------+-----------+
> > | row 1, col 1 | column 2 | column 3 | column 4 |
> > +--------------+----------+-----------+-----------+
> > | row 2 | Use the command ``ls | more``. |
> > +--------------+----------+-----------+-----------+
> > | row 3 | | | |
> > +--------------+----------+-----------+-----------+
> >
> > ... is silly. You are drawing tables in text. Imagine the amount of
> > work
> > required to add or remove a column.
> >
> > The reason one would use this is if it would be desirable for the
> > documentation to look presentable in a plain text source file.
> 
> --
> Michael Wilde
> Computation Institute, University of Chicago
> Mathematics and Computer Science Division
> Argonne National Laboratory

-- 
Michael Wilde
Computation Institute, University of Chicago
Mathematics and Computer Science Division
Argonne National Laboratory