Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 $ 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! |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
It looks great.
Thanks a lot! Sgruttendio |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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. |=== a| :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 Copyright \(C) 2008 {author}. 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. ... [show rest of quote] Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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. 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, |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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:
... [show rest of quote] Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by sgruttendio
On Thu, Aug 25, 2016 at 4:25 PM, Dan Allen <[hidden email]> wrote:
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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:
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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:
... [show rest of quote] Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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! ls-man.pdf (39K) Download Attachment |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by sgruttendio
Here you put your man page name, such as: |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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:
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux |
Free forum by Nabble | Edit this page |