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

[Ketan Maheshwari]

Hello,

Check out the following:

http://diveintopython3.org

I thought they have a beautiful layout and if you see one of the chapters
the code and its associated description has a nice highlight feature.
Additionally the text into blue boxes that appears on the side gives it more
elegance. e.g.

http://diveintopython3.org/strings.html

I am looking into how they are generated; meanwhile I thought to push it
here just in case someone knows already the strategy used to generate these
pages.

>From the footer links, seems the pages are available in multiple languages.
This kinda indicates they are autogenerated.

Regards,
Ketan

On Tue, Mar 1, 2011 at 9:34 PM, Michael Wilde <wilde at mcs.anl.gov> wrote:

> 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
>
> _______________________________________________
> Swift-devel mailing list
> Swift-devel at ci.uchicago.edu
> http://mail.ci.uchicago.edu/mailman/listinfo/swift-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/swift-devel/attachments/20110302/9f7b877e/attachment.html>