more Documents written using AsciiDoc

119 views
Skip to first unread message

Suraj Kurapati

unread,
Apr 23, 2011, 6:06:30 AM4/23/11
to asci...@googlegroups.com
Hello,

Some of my open-source projects' manuals are written in AsciiDoc:

* http://snk.tuxfamily.org/lib/detest/
* http://snk.tuxfamily.org/lib/ember/
* http://snk.tuxfamily.org/lib/inochi/
* http://snk.tuxfamily.org/lib/rumai/

They use a little extra CSS to make the TOC stick to the viewport:
https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css

Also, they are pre-processed as eRuby templates, so parts of them
are generated dynamically. That's the great thing about AsciiDoc
being a plain-text input format: you can write tools to write it!

If you find them worthy of mention, then please add them to the
"Documents written using AsciiDoc" section on the AsciiDoc website.

Cheers and thanks for AsciiDoc!

Hongli Lai

unread,
Apr 23, 2011, 4:48:01 PM4/23/11
to asciidoc
That's pretty sweet, I want to use that template for the Phusion
Passenger manual. Do you have the tools/configs anywhere?

On Apr 23, 12:06 pm, Suraj Kurapati <sun...@gmail.com> wrote:
> Hello,
>
> Some of my open-source projects' manuals are written in AsciiDoc:
>
> *http://snk.tuxfamily.org/lib/detest/
> *http://snk.tuxfamily.org/lib/ember/
> *http://snk.tuxfamily.org/lib/inochi/
> *http://snk.tuxfamily.org/lib/rumai/

Suraj Kurapati

unread,
Apr 23, 2011, 5:38:57 PM4/23/11
to asci...@googlegroups.com
On Sat, Apr 23, 2011 at 1:48 PM, Hongli Lai <hon...@phusion.nl>
wrote:

> On Apr 23, 12:06 pm, Suraj Kurapati <sun...@gmail.com> wrote:
>> Some of my open-source projects' manuals are written in AsciiDoc:
>>
> That's pretty sweet, I want to use that template for the Phusion
> Passenger manual. Do you have the tools/configs anywhere?

Yes, my manuals are built with Inochi[1], particularly this file[2].
There's also the extra CSS[3] that sticks the TOC to the viewport.

[1] http://snk.tuxfamily.org/lib/inochi/
[2] https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.rake
[3] https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css

Stuart Rackham

unread,
Apr 23, 2011, 11:08:50 PM4/23/11
to asci...@googlegroups.com
Hi Suraj

On 23/04/11 22:06, Suraj Kurapati wrote:
> Hello,
>
> Some of my open-source projects' manuals are written in AsciiDoc:
>
> * http://snk.tuxfamily.org/lib/detest/
> * http://snk.tuxfamily.org/lib/ember/
> * http://snk.tuxfamily.org/lib/inochi/
> * http://snk.tuxfamily.org/lib/rumai/
>
> They use a little extra CSS to make the TOC stick to the viewport:
> https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css

That's a much better way to display the TOC and because you've used CSS instead
of frames it's very easy to integrate with the existing AsciiDoc outputs. I've
copied your CSS and implemented a 'toc2' attribute to generate this style of TOC
directly from AsciiDoc:
http://code.google.com/p/asciidoc/source/detail?r=d33f1f74e4ce8802ab105d7a2d5be9c1006e799d

Example usage:

asciidoc -a toc2 mydoc.txt


>
> Also, they are pre-processed as eRuby templates, so parts of them
> are generated dynamically. That's the great thing about AsciiDoc
> being a plain-text input format: you can write tools to write it!
>
> If you find them worthy of mention, then please add them to the
> "Documents written using AsciiDoc" section on the AsciiDoc website.

I've added them to the list, will go up to the website at the next release:
http://code.google.com/p/asciidoc/source/detail?r=cc1228ee58e72fab1ea08b7a8fee32a660c5e8e7

Let me know if there's anything that needs changing.


Cheers, Stuart

Lex Trotman

unread,
Apr 24, 2011, 4:13:27 AM4/24/11
to asci...@googlegroups.com
Hi Suraj, Stuart,

>> Some of my open-source projects' manuals are written in AsciiDoc:
>>
>> * http://snk.tuxfamily.org/lib/detest/
>> * http://snk.tuxfamily.org/lib/ember/
>> * http://snk.tuxfamily.org/lib/inochi/
>> * http://snk.tuxfamily.org/lib/rumai/
>>
>> They use a little extra CSS to make the TOC stick to the viewport:
>> https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css
>

@Suraj, nice sites and a nice way of creating them.

> That's a much better way to display the TOC and because you've used CSS
> instead of frames it's very easy to integrate with the existing AsciiDoc
> outputs. I've copied your CSS and implemented a 'toc2' attribute to generate
> this style of TOC directly from AsciiDoc:
> http://code.google.com/p/asciidoc/source/detail?r=d33f1f74e4ce8802ab105d7a2d5be9c1006e799d
>
> Example usage:
>
>  asciidoc -a toc2 mydoc.txt
>

@Stuart, thanks for adding, will be useful.

But of course a little niggle :-) toc2 is pretty meaningless, can the
attribute be renamed sidetoc or lefttoc or similar.

Cheers
Lex

Stuart Rackham

unread,
Apr 24, 2011, 5:42:24 PM4/24/11
to asci...@googlegroups.com

The same thought occurred to me, but then toc (in the context of multiple TOC
names) is also fairly meaningless. So the question is do we have one generic TOC
name plus one meaningful one or two meaningless generic TOC names -- I opted for
consistency and brevity.

Is obsessing over names pedantic? I don't think so, it's one of the most
important aspects of writing clear meaningful code, and it's probably the most
neglected.

Cheers, Stuart

>
> Cheers
> Lex
>

Lex Trotman

unread,
Apr 24, 2011, 7:36:37 PM4/24/11
to asci...@googlegroups.com
>> @Stuart, thanks for adding, will be useful.
>>
>> But of course a little niggle :-)  toc2 is pretty meaningless, can the
>> attribute be renamed sidetoc or lefttoc or similar.
>
> The same thought occurred to me, but then toc (in the context of multiple
> TOC names) is also fairly meaningless. So the question is do we have one
> generic TOC name plus one meaningful one or two meaningless generic TOC
> names -- I opted for consistency and brevity.
>

Hmmm, ok, I guess toc is such a common abbreviation of table of
contents that I saw it as a reasonable name for an attribute
controlling the canonical toc rather than meaningless.

I guess in this era of txting toc2 means toc too so its meaningful 2 :-)

> Is obsessing over names pedantic? I don't think so, it's one of the most
> important aspects of writing clear meaningful code, and it's probably the
> most neglected.

No of course its not pedantic, except for trying to make loop counters
meaningful. If all its there for is to count from 1 to 10 call it
loop_counter if you *must* have a long name, otherwise call it i, j, k
...why yes I did start with Fortran programming, why do you ask? :-)
(Clambers awkwardly off his soapbox)

Cheers
Lex

Suraj Kurapati

unread,
Apr 24, 2011, 8:48:31 PM4/24/11
to asci...@googlegroups.com
On Sat, Apr 23, 2011 at 8:08 PM, Stuart Rackham <srac...@gmail.com>
wrote:

>> use a little extra CSS to make the TOC stick to the viewport:
>> https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css
>
> That's a much better way to display the TOC and because you've
> used CSS instead of frames it's very easy to integrate with the
> existing AsciiDoc outputs.

Thanks! That sidebar TOC was inspired by the old Node.js manual.

> I've copied your CSS and implemented a 'toc2' attribute to
> generate this style of TOC directly from AsciiDoc:
> http://code.google.com/p/asciidoc/source/detail?r=d33f1f74e4ce8802ab105d7a2d5be9c1006e799d

I'm not sure if you really wanted to copy this portion of the CSS:

@media print {
#toc {
display: none;
}
}

Because the AsciiDoc HTML default is to print with the TOC, right?

>> If you find them worthy of mention, then please add them to the
>> "Documents written using AsciiDoc" section on the AsciiDoc
>> website.
>
> I've added them to the list, will go up to the website at the next
> release:

Awesome, thanks for the mention!

Stuart Rackham

unread,
Apr 24, 2011, 8:49:27 PM4/24/11
to asci...@googlegroups.com

My first introduction to computers was Fortran, IBM punched card batch system, I
swore I'd never touch a computer again -- changed my mind when I started using
DEC BASIC-PLUS on a PDP-11 a couple of years later.

Cheers, Stuart

Stuart Rackham

unread,
Apr 24, 2011, 9:50:59 PM4/24/11
to asci...@googlegroups.com

On 25/04/11 12:48, Suraj Kurapati wrote:
> On Sat, Apr 23, 2011 at 8:08 PM, Stuart Rackham<srac...@gmail.com>
> wrote:
>>> use a little extra CSS to make the TOC stick to the viewport:
>>> https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css
>>
>> That's a much better way to display the TOC and because you've
>> used CSS instead of frames it's very easy to integrate with the
>> existing AsciiDoc outputs.
>
> Thanks! That sidebar TOC was inspired by the old Node.js manual.
>
>> I've copied your CSS and implemented a 'toc2' attribute to
>> generate this style of TOC directly from AsciiDoc:
>> http://code.google.com/p/asciidoc/source/detail?r=d33f1f74e4ce8802ab105d7a2d5be9c1006e799d
>
> I'm not sure if you really wanted to copy this portion of the CSS:
>
> @media print {
> #toc {
> display: none;
> }
> }
>
> Because the AsciiDoc HTML default is to print with the TOC, right?

You are right, I didn't test this out and just assumed the TOC viewport would be
positioned on the left instead of at the head of the document. Changed in trunk:
http://code.google.com/p/asciidoc/source/detail?r=bc56adfafc496301e5b91b86f4bf924c842db9c0

Cheers, Stuart

Lex Trotman

unread,
Apr 24, 2011, 10:10:56 PM4/24/11
to asci...@googlegroups.com
>> No of course its not pedantic, except for trying to make loop counters
>> meaningful.  If all its there for is to count from 1 to 10 call it
>> loop_counter if you *must* have a long name, otherwise call it i, j, k
>> ...why yes I did start with Fortran programming, why do you ask? :-)
>
> My first introduction to computers was Fortran, IBM punched card batch
> system, I swore I'd never touch a computer again -- changed my mind when I
> started using DEC BASIC-PLUS on a PDP-11 a couple of years later.
>
> Cheers, Stuart
>

Ahhhh memories, the cellulose based UI, perforated for input and
printed for output, started with batch punched cards on a Dec PDP-10
then interactive with an ASR-33 Teletype with paper tape for off-line
preparation and storage. Some years and a degree later was
programming assembler on a PDP-11/40 running RSX-11M when *IT*
happened, we installed an early Berkley distribution of Unix, and
trumpets blared and angels chorused and the assembler translated
one-to-one into C.

Cheers
Lex

>
>> (Clambers awkwardly off his soapbox)
>>
>> Cheers
>> Lex
>>
>

> --
> You received this message because you are subscribed to the Google Groups
> "asciidoc" group.
> To post to this group, send email to asci...@googlegroups.com.
> To unsubscribe from this group, send email to
> asciidoc+u...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/asciidoc?hl=en.
>
>

Russell Dickenson

unread,
Apr 25, 2011, 6:45:48 AM4/25/11
to asci...@googlegroups.com
On 25 April 2011 12:10, Lex Trotman <ele...@gmail.com> wrote:
>>> No of course its not pedantic, except for trying to make loop counters
>>> meaningful.  If all its there for is to count from 1 to 10 call it
>>> loop_counter if you *must* have a long name, otherwise call it i, j, k
>>> ...why yes I did start with Fortran programming, why do you ask? :-)
>>
>> My first introduction to computers was Fortran, IBM punched card batch
>> system, I swore I'd never touch a computer again -- changed my mind when I
>> started using DEC BASIC-PLUS on a PDP-11 a couple of years later.
>>
>> Cheers, Stuart
>>
>
> Ahhhh memories, the cellulose based UI, perforated for input and
> printed for output, started with batch punched cards on a Dec PDP-10
> then interactive with an ASR-33 Teletype with paper tape for off-line
> preparation and storage.  Some years and a degree later was
> programming assembler on a PDP-11/40 running RSX-11M when *IT*
> happened, we installed an early Berkley distribution of Unix, and
> trumpets blared and angels chorused and the assembler translated
> one-to-one into C.
>
> Cheers
> Lex
>
>>
>>> (Clambers awkwardly off his soapbox)
>>>
>>> Cheers
>>> Lex


*sigh* The rest of the AsciiDoc community is trying to present itself
as young, fresh and vibrant and in just two postings all that work has
been undone. :( The idea is to quote references to Web 2.0 terms and
throwing around words like "cloud" and phrases like "pushing the
envelope". Reminiscing about what happened in the 1970s isn't going
attract a young crowd, is it!?

Stuart and Lex - well done for making it this far. :P

(In case it's not quite clear, this entire post is a joke, or at least
an attempt at one).


--
Russell Dickenson

Lex Trotman

unread,
Apr 25, 2011, 7:13:40 AM4/25/11
to asci...@googlegroups.com
>
> *sigh* The rest of the AsciiDoc community is trying to present itself
> as young, fresh and vibrant and in just two postings all that work has
> been undone. :( The idea is to quote references to Web 2.0 terms and
> throwing around words like "cloud" and phrases like "pushing the
> envelope". Reminiscing about what happened in the 1970s isn't going
> attract a young crowd, is it!?
>
> Stuart and Lex - well done for making it this far. :P
>
> (In case it's not quite clear, this entire post is a joke, or at least
> an attempt at one).
>
>
> --
> Russell Dickenson
>

Funnily enough the "cloud" has "pushed the envelope" so far that it
has come right back around to centralised processing with dumb
terminals, just like timesharing in the 70s :-)

Cheers
Lex

Ed Keith

unread,
Apr 25, 2011, 7:34:36 AM4/25/11
to asci...@googlegroups.com
--- On Mon, 4/25/11, Lex Trotman <ele...@gmail.com> wrote:

And languages that run on virtual machines, just like UCSD-pascal. The '70s are making a comeback.

-EdK

Ed Keith
e_...@yahoo.com

Blog: edkeith.blogspot.com

Hongli Lai

unread,
Apr 25, 2011, 8:03:05 AM4/25/11
to asciidoc
On Apr 23, 11:38 pm, Suraj Kurapati <sun...@gmail.com> wrote:
> Yes, my manuals are built with Inochi[1], particularly this file[2].
> There's also the extra CSS[3] that sticks the TOC to the viewport.
>
> [1]http://snk.tuxfamily.org/lib/inochi/
> [2]https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.rake
> [3]https://github.com/sunaku/inochi/blob/master/lib/inochi/tasks/2-man.css

Perfect, you do unindentation with ERB templates! I needed that for
the Phusion Passenger manual for which large parts of texts are
identical between the Nginx version and the Apache version.

Lex Trotman

unread,
Apr 25, 2011, 8:03:57 AM4/25/11
to asci...@googlegroups.com

Still, some things have changed for the better, runoff can't hold a
candle to Asciidoc. Compare the man pages that were the start of this
thread to some original 70s versions, in single fixed width font, no
emphasis. italics or colours (unless its black or white). :-)

Cheers
Lex

Suraj Kurapati

unread,
Apr 25, 2011, 5:23:03 PM4/25/11
to asci...@googlegroups.com
On Mon, Apr 25, 2011 at 5:03 AM, Hongli Lai <hon...@phusion.nl>
wrote:

> On Apr 23, 11:38 pm, Suraj Kurapati <sun...@gmail.com> wrote:
>> Yes, my manuals are built with Inochi[1]
>>
>> [1]http://snk.tuxfamily.org/lib/inochi/

>
> Perfect, you do unindentation with ERB templates!

Yes, that is a key feature of my Ember eRuby template processor:
http://snk.tuxfamily.org/lib/ember/#_unindent_block_content

> I needed that for the Phusion Passenger manual for which large
> parts of texts are identical between the Nginx version and the
> Apache version.

You can also store content in lambdas (as opposed to strings):
https://github.com/sunaku/rumai/blob/master/USAGE#L7

Tomek Kaczanowski

unread,
Apr 26, 2011, 2:45:30 AM4/26/11
to asciidoc
> >> Example usage:
> >>   asciidoc -a toc2 mydoc.txt
>
> > @Stuart, thanks for adding, will be useful.
>
> > But of course a little niggle :-)  toc2 is pretty meaningless, can the
> > attribute be renamed sidetoc or lefttoc or similar.
>
> The same thought occurred to me, but then toc (in the context of multiple TOC
> names) is also fairly meaningless. So the question is do we have one generic TOC
> name plus one meaningful one or two meaningless generic TOC names -- I opted for
> consistency and brevity.
Maybe something like:
asciidoc -a toc mydoc.txt (to produce default toc)
asciidoc -a toc -a toc_style=whatever (to produce some variant)

what do you think?

--
cheers,
Tomek Kaczanowski

Lex Trotman

unread,
Apr 26, 2011, 3:07:11 AM4/26/11
to asci...@googlegroups.com

As its currently coded it has to be two mutually exclusive attributes,
your way would mean changing the implementation

Cheers
Lex

Tomek Kaczanowski

unread,
Apr 26, 2011, 4:02:51 AM4/26/11
to asciidoc


On 26 Kwi, 09:07, Lex Trotman <ele...@gmail.com> wrote:
I see. But that would allow asciidoc to support any number of toc
versions in the future, so maybe this is worth the trouble?

--
cheers,
Tomek Kaczanowski

Lex Trotman

unread,
Apr 26, 2011, 4:28:22 AM4/26/11
to asci...@googlegroups.com
> I see. But that would allow asciidoc to support any number of toc
> versions in the future, so maybe this is worth the trouble?
>

There is nothing stopping there being any number of mutually exclusive
toc styles, from toc3 to tocinfinity :-)

Cheers
Lex

> --
> cheers,
> Tomek Kaczanowski

Reply all
Reply to author
Forward
0 new messages