Asciidoctor :: Discussion

Embed man pages in a book

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

15 messages Options

sgruttendio

Embed man pages in a book

Hi everybody,

I am new to Asciidoc and Asciidoctor. I am considering using them to write a computer science textbook.

My question is: what is one supposed to do when a book has to include (among other "normal" book content) properly formatted manpages (that is, man pages formatted, more or less, in the traditional "terminal" way)?

I see there is a "book" doctype and a "manpage" doctype but I understand only a doctype is allowed in a project. Is that correct? Am I missing any important concept? Which is the best way to embed man pages in a book?

Thanks in advance for any help

Sgruttendio

eskwayrd

Re: Embed man pages in a book

sgruttendio wrote

My question is: what is one supposed to do when a book has to include (among other "normal" book content) properly formatted manpages (that is, man pages formatted, more or less, in the traditional "terminal" way)?

I'd expect there are plenty of ways to accomplish this, but my first inclination is to use source blocks.

Suppose your "book" looks like this:

= Manpage Inclusion

Here is a manpage:

[source,manpage]
----
include::manpage.txt[]
----

Then you'd need to create manpage.txt, perhaps like this:

$ man ls > manpage.txt

Then:

$ asciidoctor book.adoc

Obviously, with many manpages to be included, you'd use a sensible naming scheme.

I hope that helps!

sgruttendio

Re: Embed man pages in a book

It looks great.

Thanks a lot!

Sgruttendio

sgruttendio

Re: Embed man pages in a book

Well, I imagine this question is going to look trivial. I didn't ask it before since I thought the problem didn't exist.

Once embedded the manpage in my book as you suggested. It looks ok, but... it has no formatting (i.e. bold characters for NAME, SYNOPSIS, no underlined words, like "file" etc.). I thought, for example, adding stars around the words would suffice (*file*), but no, it is rendered verbatim. What's the key to the solution?

Sorry to bother you again

Thanks

Sgruttendio

mojavelinux

Re: Embed man pages in a book

Administrator

There's one way to get around the limitation of a single doctype per document. The trick is to use an AsciiDoc table cell. AsciiDoc table cells support an embedded document and allow the doctype to be modified. You can use this approach to embed a man page written in AsciiDoc inside of another document. You can find an example below.

However, there are some limitations with this approach. For instance, attributes defined in the man page document that are already defined in the main document get ignored. If I were doing this for a real book, I would definitely write a block extension that executed Asciidoctor separately on the nested man document, then insert the HTML back into the document (as a pass block). That way I would know that the document trees were properly isolated.

= My Book

Author Name

:doctype: book

Introductory text.

|===

:doctype: manpage

:showtitle:

= eva(1)

Andrew Stanton

v1.0.0

:manmanual: EVE

:mansource: EVE

== NAME

eve - analyzes an image to determine if it's a picture of a life form

== SYNOPSIS

*eve* ['OPTION']... 'FILE'...

== OPTIONS

*-o, --out-file*=_OUT_FILE_::

Write result to file _OUT_FILE_.

*-c, --capture*::

Capture specimen if it's a picture of a life form.

== EXIT STATUS

*0*::

Success.

Image is a picture of a life form.

*1*::

Failure.

Image is not a picture of a life form.

== RESOURCES

*Project web site:* http://eve.example.org

== COPYING

Free use of this software is granted under the terms of the MIT License.

|===

More text.

-Dan

On Wed, Aug 24, 2016 at 10:58 AM, sgruttendio [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Well, I imagine this question is going to look trivial. I didn't ask it before since I thought the problem didn't exist.

Once embedded the manpage in my book as you suggested. It looks ok, but... it has no formatting (i.e. bold characters for NAME, SYNOPSIS, no underlined words, like "file" etc.). I thought, for example, adding stars around the words would suffice (*file*), but no, it is rendered verbatim. What's the key to the solution?

Sorry to bother you again

Thanks

Sgruttendio

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Embed-man-pages-in-a-book-tp4906p4909.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

sgruttendio

Re: Embed man pages in a book

Thank you for your answer, Dan.

Now I realize what I am looking for is not that easy.

The solution you posted is nice but it lacks monospaced text, which I believe is a must in a man page.

Is there any way to fix this or this is about "writing a block extension", as you hinted? In that case I would think twice before adopting asciidoc for my book (my default tool would be LaTeX but I was trying to solve the problem of its lack of a satisfactory epub support)

Best
Sgruttendio

mojavelinux

Re: Embed man pages in a book

Administrator

On Thu, Aug 25, 2016 at 4:58 AM, sgruttendio [via Asciidoctor :: Discussion] <[hidden email]> wrote:

The solution you posted is nice but it lacks monospaced text, which I believe is a must in a man page.

We are clearly talking about different things then. You want the man page to look like it looks in the man pager, but as HTML. The first thing you need to do is figure out how to achieve that without Asciidoctor. I tried man2html, roffit and man --html='w3m -dump_source`, but all gave me output very close to what the manpage converter in Asciidoctor provides. I don't know if there's a tool to make an HTML version of exactly what you see in the man pager, monospace and all.

> Is there any way to fix this or this is about "writing a block extension", as you hinted?

I strongly encourage you not to fear extensions. If you're using Asciidoctor seriously, this is something you should know. I think it would be ridiculous to select another tool over Asciidoctor to avoid having to write an extension. Asciidoctor extensions are so easy to write and so powerful, they'll absolutely save you time and headaches in the end.

It seems to me the main challenge here is simply being able to define the requirement. Once you can define your requirement clearly, the path to getting the output you want really isn't that far away. You seem to want to capture the man pager display and render that faithfully as HTML (assuming HTML is your output). If you can find a way to do that step, then we can wire that step into Asciidoctor easily.

Cheers,

-Dan

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

I found one way to get the HTML you are seeking. It's not pretty, but it shows that a path does exist.

COMMAND=ls

vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

(this requires the man plugin for vim, available at https://github.com/vim-utils/vim-man).

You could also look into neoman.vim, available at https://github.com/nhooyr/neoman.vim.

-Dan

On Thu, Aug 25, 2016 at 4:10 PM, Dan Allen <[hidden email]> wrote:

On Thu, Aug 25, 2016 at 4:58 AM, sgruttendio [via Asciidoctor :: Discussion] <[hidden email]> wrote:
The solution you posted is nice but it lacks monospaced text, which I believe is a must in a man page.

We are clearly talking about different things then. You want the man page to look like it looks in the man pager, but as HTML. The first thing you need to do is figure out how to achieve that without Asciidoctor. I tried man2html, roffit and man --html='w3m -dump_source`, but all gave me output very close to what the manpage converter in Asciidoctor provides. I don't know if there's a tool to make an HTML version of exactly what you see in the man pager, monospace and all.

> Is there any way to fix this or this is about "writing a block extension", as you hinted?

I strongly encourage you not to fear extensions. If you're using Asciidoctor seriously, this is something you should know. I think it would be ridiculous to select another tool over Asciidoctor to avoid having to write an extension. Asciidoctor extensions are so easy to write and so powerful, they'll absolutely save you time and headaches in the end.

It seems to me the main challenge here is simply being able to define the requirement. Once you can define your requirement clearly, the path to getting the output you want really isn't that far away. You seem to want to capture the man pager display and render that faithfully as HTML (assuming HTML is your output). If you can find a way to do that step, then we can wire that step into Asciidoctor easily.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

On Thu, Aug 25, 2016 at 4:25 PM, Dan Allen <[hidden email]> wrote:

COMMAND=ls
vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

Correction. That should be on one line.

COMMAND=ls vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

One more time. Missing the semi-colon:

COMMAND=ls; vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w! `pwd`/$COMMAND.html" -c ':qa!'

On Thu, Aug 25, 2016 at 4:26 PM, Dan Allen <[hidden email]> wrote:

On Thu, Aug 25, 2016 at 4:25 PM, Dan Allen <[hidden email]> wrote:
COMMAND=ls
vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

Correction. That should be on one line.

COMMAND=ls vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

Of course, you need to extract the content of the <body> tag to insert that into your document...but that's all pretty reasonable.

-Dan

On Thu, Aug 25, 2016 at 4:28 PM, Dan Allen <[hidden email]> wrote:

One more time. Missing the semi-colon:

COMMAND=ls; vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w! `pwd`/$COMMAND.html" -c ':qa!'

On Thu, Aug 25, 2016 at 4:26 PM, Dan Allen <[hidden email]> wrote:

On Thu, Aug 25, 2016 at 4:25 PM, Dan Allen <[hidden email]> wrote:
COMMAND=ls
vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

Correction. That should be on one line.

COMMAND=ls vim -c ":Man $COMMAND" -c ':TOhtml' -c ":w `pwd`/$COMMAND.html" -c ':qa!'

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

sgruttendio

Re: Embed man pages in a book

Hi Dan,

first of all, thanks again for all the effort you put into answering my doubts.

I wish here to ask a question and to make clear what I need.

First the question: which is in your opinion the best reading to start with writing extensions?

Then a clarification on what I need: my main concern is PDF. I wish to publish a real paper book so that is the main path for me. HTML is appreciated but it is not the main thing. This said, the solution suggested by eskwayrd was practically perfect for me. The only thing it lacks is bold and underlined for some words. But, it is so simple and effective that, should I choose Asciidoc to write my book, perhaps I would drop those requirements for the sake of simplicity.

Thanks
Sgruttendio

mojavelinux

Re: Embed man pages in a book

Administrator

Sgruttendio,

We're certainly glad to have you here! I think what you'll find is that this is a great community that loves to solve problems together. That's why I encourage you to stay. If you run into challenges, you'll find a lot of shoulders to lean on around here.

I have good news for you regarding the solution I discovered...which builds on what @eskwayrd initially proposed. If, ahead of time, you use the script I made to generate the HTML versions of the man page, it's possible to use that output in PDF. Asciidoctor PDF supports an "HTML-lite" for inline formatting.

COMMAND=$1

MANWIDTH=80 man $COMMAND | \

col -b | \

vim -c 'set ft=man nomod' \

-c ':TOhtml' \

-c ":w! `pwd`/$COMMAND.html" \

-c ':qa!' - && \

sed -i -n -e '/^<pre /,/^<\/pre>$/{ /^<pre /d; /^<\/pre>$/d; s/<span[^>]\+>$.*$<\/span>/<strong>\1<\/strong>/; p }' $COMMAND.html

unset COMMAND

Then embed the result in AsciiDoc:

[subs=none]

----

include::ls.html[]

----

Just to prove it's possible, I attached an example of the ls man page included in a PDF generated by Asciidoctor PDF.

In the end, it just requires some transformation magic. After all, it's just text ;)

> Which is in your opinion the best reading to start with writing extensions?

A good starting point is http://asciidoctor.org/docs/user-manual/#extensions. I'll admit that it does need some updating, but if you ask questions, I'll update the documentation in real time ;)

I also recommend studying the extensions-lab to see examples. There are lots and more added every month. https://github.com/asciidoctor/asciidoctor-extensions-lab

Cheers!

-Dan

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

ls-man.pdf (39K) Download Attachment

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

On Fri, Aug 26, 2016 at 5:12 AM, Dan Allen <[hidden email]> wrote:

COMMAND=$1

Here you put your man page name, such as:

COMMAND=ls

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

mojavelinux

Re: Embed man pages in a book

Administrator

In reply to this post by sgruttendio

Of course, if Pygments or Rouge supported source highlighting of a typeset man page, then it would be as simple as:

:source-highlighter: rouge

[source,man]

----

include::ls.man[]

----

But there's no available lexer atm. But that is a route you could take. It's pretty easy to match the headings and options in a typeset man page. You can use the vim highlighter as a starting point. See https://github.com/vim/vim/blob/master/runtime/syntax/man.vim

-Dan

On Fri, Aug 26, 2016 at 5:13 AM, Dan Allen <[hidden email]> wrote:

On Fri, Aug 26, 2016 at 5:12 AM, Dan Allen <[hidden email]> wrote:
COMMAND=$1

Here you put your man page name, such as:

COMMAND=ls

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux