LinuxQuestions.org
Review your favorite Linux distribution.
Go Back   LinuxQuestions.org > Forums > Linux Forums > Linux - Distributions > Slackware
User Name
Password
Slackware This Forum is for the discussion of Slackware Linux.

Notices


Reply
  Search this Thread
Old 12-13-2014, 03:33 AM   #1
pdi
Member
 
Registered: May 2008
Posts: 50

Rep: Reputation: 59
asciidoc mini howto


My new toy is asciidoc, part of Slackware. I slowly came to understand its many advantages when used for keeping notes on various Slackware subjects. What put me on this tack was this interesting read, Living the Future of Technical Writing.

For those of you who haven't come across it, here's a brief introduction.

I've always kept notes in plain text so that I can use gpm to copy paste commands, but devising a structure for a text file only gets you so far. asciidoc provides this to a much higher degree of consistency. If you couple that with vim highlighting (for those who prefer it) it really helps visually.

On top of that, asciidoc can produce html files. This is an added bonus because, even on a tty with lynx, it allows you to jump to relevant files by following a link, thus tying the entire body of notes together.

Another strong point is that it can work in tandem with man2html to provide html access to all man pages on the fly. Not only is it useful to remind yourself of some man details in the notes, but man pages themselves become navigable as well.

Lastly, using txt2tags you can output the asciidoc file in dokuwiki format, hopefully needing only slight syntax corrections to contribute to the Slackware Documentation Project.

EDIT: txt2tags is the wrong tool, the perl module HTML::WikiConverter::dokuWiki does the job.

Apart from the more technical matters, seeing the html output nudges you to write better documentation.

I'm attaching two example asciidoc files. Uploading html files is not possible, but you can easily make them:

Code:
asciidoc \
  -b xhtml11 \
  -a icons -a max-width=45em \
  -a iconsdir=/etc/asciidoc/images/icons \
  -a stylesdir=/etc/asciidoc/stylesheets \
  FILENAME
You won't get the source highlighting, but the files have instructions to get you started on that.

EDIT: BTW, for those wondering, the mini howto is in the attached files.
Attached Files
File Type: txt F901_asciidoc.txt (4.2 KB, 82 views)
File Type: txt F910_man2html.txt (2.8 KB, 34 views)

Last edited by pdi; 12-18-2014 at 06:38 AM. Reason: Correct tool for DokuWiki conversion.
 
Old 12-13-2014, 04:00 AM   #2
Didier Spaier
LQ Addict
 
Registered: Nov 2008
Location: Paris, France
Distribution: Slint64-15.0
Posts: 11,048

Rep: Reputation: Disabled
Thanks for sharing. For your information Slint's website http://slint.fr exclusively uses asciidoc: no javascript, no database, just static pages xhtml + css. Clicking on Page Source on the left hand menu shows the source text file, as in asciidoc's web site. Rebuiding the website (95 pages) takes less than 4 minutes: asciidoctor is way faster, but that's good enough for me. As a side note localized pages are built through conversions asciidoc text => PO format => asciidoc text => xhtml, thanks to po4a + gettext + asciidoc.
 
1 members found this post helpful.
Old 12-13-2014, 05:10 AM   #3
kjhambrick
Senior Member
 
Registered: Jul 2005
Location: Round Rock, TX
Distribution: Slackware64 15.0 + Multilib
Posts: 2,159

Rep: Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512Reputation: 1512
Very nice, pdi !

I read about asciidoc just this week while looking for tools to manage a nasty documentation project looming ahead of me.

You've helped me decide to use asciidoc !

Thanks and thanks to Didier !

-- kjh

Last edited by kjhambrick; 12-13-2014 at 05:12 AM. Reason: add thank you to Didier
 
Old 12-13-2014, 06:37 AM   #4
Gerard Lally
Senior Member
 
Registered: Sep 2009
Location: Leinster, IE
Distribution: Slackware, NetBSD
Posts: 2,176

Rep: Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761
Thanks for the heads-up. These alternatives to bloated and inefficient word processors (with their ugly output and equally ugly interface) are very interesting to me. When I was going through the Irish education system everything was Microsoft Windows and Microsoft Word. We didn't know any better. The teachers didn't -- and still don't -- know any better either. It didn't help that Microsoft engaged (and still engages?) in anti-competitive practices by giving away licences to teachers and schools for nothing or next to nothing.

Imagine my surprise and excitement when I stumbled upon alternatives like Org-mode, TeX and groff. The older Unix and Linux heads here will laugh, given how long troff/groff and TeX have been around, but for me, just coming upon them relatively recently, a whole new world has opened up, an exciting world which puts powerful and aesthetic document production in the hands of the layman. How I wish I knew about them when I was writing a thesis 20 years ago!

Since I really like minimalist systems like Crux, NetBSD and a stripped Slack, which pretty much rules out the heavy and complex TeX, I use either Org-mode or groff (with Peter Schaffter's excellent MOM macros), depending on the situation. Both of them are powerful and both of them produce typographically pleasing output for print and screen, with a learning curve that is well worth the trouble.

I will certainly play around with asciidoc now that you mention it. Any system which takes plain-text input and converts that to output worthy of a professional typesetter is head and shoulders above the distracting, ugly and inefficient word-processing software I grew up with.
 
Old 12-15-2014, 07:21 AM   #5
pdi
Member
 
Registered: May 2008
Posts: 50

Original Poster
Rep: Reputation: 59
Didier, yes, I'm aware of SLINT's asciidoc infrastructure. In fact it reassured me I was on the right track choosing asciidoc :-) BTW, I'm aware it's not related to SLINT, but the small number of el man pages in Slackware don't play well with a utf8 locale and converting them wouldn't take much effort. I suppose this is the turf of the Linux man-pages project.

kjhambrick, glad the post helped a little :-)

gezley, Org-mode was entirely off my radar, thanks for making it blip.
 
Old 12-17-2014, 01:57 AM   #6
dederon
Member
 
Registered: Oct 2013
Posts: 104

Rep: Reputation: 54
Quote:
Originally Posted by gezley View Post
groff (with Peter Schaffter's excellent MOM macros)
i write all my letters with groff/mom, and i never looked back. libre-/openoffice is windows software anyway - fat, bloated and using a file format which can't be processed with standard unix tools. it's a shame that 98% of the linux users rely on this crap. reminds me of theo de raadt: "linux people do what they do because they hate microsoft. we do what we do because we love unix.". open-/libreoffice is the proof that most linux users just want a convenient, microsoft-like, free os.

asciidoc has become too bloated for my taste, so i use markdown for technical papers.
 
Old 12-17-2014, 04:24 AM   #7
Alien Bob
Slackware Contributor
 
Registered: Sep 2005
Location: Eindhoven, The Netherlands
Distribution: Slackware
Posts: 8,559

Rep: Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105Reputation: 8105
So, pdi and/or Didier, why don't you spend a few minutes to (request a Wiki account and) write this as a nice piece of knowledge in the Slackware Documentation Project wiki?
Go to http://docs.slackware.com/howtos:software:start and produce something that will benefit the community!

Eric
 
1 members found this post helpful.
Old 12-17-2014, 07:40 AM   #8
bassmadrigal
LQ Guru
 
Registered: Nov 2003
Location: West Jordan, UT, USA
Distribution: Slackware
Posts: 8,792

Rep: Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656
Quote:
Originally Posted by dederon View Post
i write all my letters with groff/mom, and i never looked back. libre-/openoffice is windows software anyway - fat, bloated and using a file format which can't be processed with standard unix tools. it's a shame that 98% of the linux users rely on this crap. reminds me of theo de raadt: "linux people do what they do because they hate microsoft. we do what we do because we love unix.". open-/libreoffice is the proof that most linux users just want a convenient, microsoft-like, free os.
I'm sorry, but if I want to do that for all my documents that need formatting, I might as well write an HTML document and put it up on my website. I don't mind doing some basic markup when on a forum, because it isn't common, but if I'm doing a massive document that needs formatting, I don't want to essentially write a webpage to do it. I want to highlight some text and then click a button to bold something or change the font. Then there's the whole portability aspect. Sending someone a .doc file means that 99% of the people who have a computer will likely be able to open it. Using a WYSIWYG editor does not mean that I want an essentially free version of Windows. How naive is that thinking? I certainly have no malice towards Microsoft. They just make a product that I don't like to use. I might question their business practices (and sanity), but I certainly don't use Linux to spite Windows. I use Linux (and Slackware specifically), because I like using it.

There's times when simplicity is best, which is why I use plaintext files for a lot of stuff, but if it is in-depth and needs to be formatted, I'm switching to a WYSIWYG editor. And just because I use SMPlayer as a front-end to mplayer rather than typing out the whole command in the console doesn't mean I want to have a free version of Windows Media Player on linux. I'm a firm believer in using the right tool for the right job. The right tool for you may not be the right tool for me. I'm not under the illusion that what's perfect for me is perfect for you. You should figure that out.
 
Old 12-17-2014, 09:37 AM   #9
kikinovak
MLED Founder
 
Registered: Jun 2011
Location: Montpezat (South France)
Distribution: CentOS, OpenSUSE
Posts: 3,453

Rep: Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154Reputation: 2154
Quote:
Originally Posted by dederon View Post
i write all my letters with groff/mom, and i never looked back. libre-/openoffice is windows software anyway - fat, bloated and using a file format which can't be processed with standard unix tools. it's a shame that 98% of the linux users rely on this crap. reminds me of theo de raadt: "linux people do what they do because they hate microsoft. we do what we do because we love unix.". open-/libreoffice is the proof that most linux users just want a convenient, microsoft-like, free os.

asciidoc has become too bloated for my taste, so i use markdown for technical papers.
Groff is still too bloated. Real men use a chisel and a big stone to write on their cavern walls.
 
1 members found this post helpful.
Old 12-17-2014, 10:55 AM   #10
dederon
Member
 
Registered: Oct 2013
Posts: 104

Rep: Reputation: 54
Quote:
Originally Posted by kikinovak View Post
Groff is still too bloated. Real men use a chisel and a big stone to write on their cavern walls.
your 2nd sentence defeated my hope that was raised by your 1st sentence. don't do that! anyway, i understand ppl who don't like groff - i wouldn't use it without the mom package.
 
Old 12-17-2014, 11:44 AM   #11
pdi
Member
 
Registered: May 2008
Posts: 50

Original Poster
Rep: Reputation: 59
Quote:
Originally Posted by Alien Bob View Post
... why don't you spend a few minutes to (request a Wiki account and) write this as a nice piece of knowledge in the Slackware Documentation Project wiki? ...
Eric, thanks for the nudge and the slackdocs account. Done: asciidoc, man2html.

EDIT: To set the record straight, Didier had already written an article about asciidoc in slackdocs :-)

Last edited by pdi; 12-18-2014 at 06:44 AM. Reason: Acknowledgement of Didier's article in slackdocs.
 
3 members found this post helpful.
Old 12-17-2014, 03:41 PM   #12
Gerard Lally
Senior Member
 
Registered: Sep 2009
Location: Leinster, IE
Distribution: Slackware, NetBSD
Posts: 2,176

Rep: Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761Reputation: 1761
Quote:
Originally Posted by bassmadrigal View Post
I'm sorry, but if I want to do that for all my documents that need formatting, I might as well write an HTML document and put it up on my website. I don't mind doing some basic markup when on a forum, because it isn't common, but if I'm doing a massive document that needs formatting, I don't want to essentially write a webpage to do it. I want to highlight some text and then click a button to bold something or change the font. Then there's the whole portability aspect. Sending someone a .doc file means that 99% of the people who have a computer will likely be able to open it. Using a WYSIWYG editor does not mean that I want an essentially free version of Windows. How naive is that thinking? I certainly have no malice towards Microsoft. They just make a product that I don't like to use. I might question their business practices (and sanity), but I certainly don't use Linux to spite Windows. I use Linux (and Slackware specifically), because I like using it.

There's times when simplicity is best, which is why I use plaintext files for a lot of stuff, but if it is in-depth and needs to be formatted, I'm switching to a WYSIWYG editor. And just because I use SMPlayer as a front-end to mplayer rather than typing out the whole command in the console doesn't mean I want to have a free version of Windows Media Player on linux. I'm a firm believer in using the right tool for the right job. The right tool for you may not be the right tool for me. I'm not under the illusion that what's perfect for me is perfect for you. You should figure that out.
I think the people who pipe plain text through something like TeX or groff already have figured it out.

The Beauty of LaTeX

Word Processors: Stupid and Inefficient

Why waste half your life with an inefficient word processor trying to do something these tools can do in a fraction of the time? Why accept ugly output when you can have output worthy of a professional typesetter? Why do otherwise intelligent people think nothing of moving the mouse half way across the screen to select a sentence and moving it back again to press that Bold button on the toolbar while looking at you with utter bemusement if you tell them it's faster and easier just to insert an inline escape? Why do people in the 21st century still send documents as doc files when the most appropriate format is the standard portable document format, aka PDF, a format which does not require the recipient to go out and buy a €100+ MS licence just to read the thing?

Last edited by Gerard Lally; 12-17-2014 at 04:17 PM.
 
2 members found this post helpful.
Old 12-18-2014, 08:07 AM   #13
bassmadrigal
LQ Guru
 
Registered: Nov 2003
Location: West Jordan, UT, USA
Distribution: Slackware
Posts: 8,792

Rep: Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656Reputation: 6656
Quote:
Originally Posted by gezley View Post
I think the people who pipe plain text through something like TeX or groff already have figured it out.

The Beauty of LaTeX

Word Processors: Stupid and Inefficient

Why waste half your life with an inefficient word processor trying to do something these tools can do in a fraction of the time? Why accept ugly output when you can have output worthy of a professional typesetter? Why do otherwise intelligent people think nothing of moving the mouse half way across the screen to select a sentence and moving it back again to press that Bold button on the toolbar while looking at you with utter bemusement if you tell them it's faster and easier just to insert an inline escape? Why do people in the 21st century still send documents as doc files when the most appropriate format is the standard portable document format, aka PDF, a format which does not require the recipient to go out and buy a €100+ MS licence just to read the thing?
People are commonly bound to the lowest common denominator. Why do you think MP3s are so prevalent when there's far better formats available? Because the hardware and software is there for MP3s. And if you need to send a document that needs editing, many people don't have the appropriate software to edit PDFs ("You mean I need something other than Adobe Reader?"). Then there's the issue that many businesses don't provide you alternatives to what is already on the system. I work for the Air Force, and it took me years to convince them to get me a license of Adobe Acrobat, but not everyone has a license (and I'll probably have to fight with them again when I move to a new base). I use it all the time. I would much rather be using alternative programs to what they provide, but the computers are locked down enough that I don't have access to them.

But another good chunk of it comes down to learnability. Do I really expect my 80 year old grandmother to learn how to markup her ascii text so that it can be properly formatted in a typesetting program? The only time I use WYSIWYG editors are at work. The Air Force has extremely difficult rules to follow for their documents. Trying to get text to fall in the correct places is difficult enough with Word. Trying to do the same thing through markup would be a nightmare! Other than work

Believe me, I understand the benefits of this... just like the benefits of keeping your formatting in CSS rather than in the html file directly. But I don't expect everyone that owns a computer to to think like a web developer. Considering some of the people I work with, that's certainly asking too much!

Oh, and while it might've been true in the past, you don't require a $100+ license to view docs anymore. There's countless free options that will open them, including Microsoft's own Word that is available online.

But my response to dederon wasn't extolling the benefits of Word Processors, but arguing that just because a Linux user uses Libre/OpenOffice instead of a text editor and a typesetting program, doesn't mean that the user is just using Linux because it's a "free version of Windows". The article about word processors being stupid and ineffecient was certainly interesting, and I wholeheartedly agree with many of the points that are brought up, but do you really expect your 80 year old grandmother or your 12 year old brother who needs to type up a document to learn how to use tex/latex? There are times when WYSIWYG are beneficial, and that is one of them.
 
Old 12-18-2014, 08:46 AM   #14
Xsane
Member
 
Registered: Jan 2014
Posts: 186

Rep: Reputation: 134Reputation: 134
Quote:
Originally Posted by pdi View Post
EDIT: To set the record straight, Didier had already written an article about asciidoc in slackdocs :-)
DOCS.SLACKWARE.COM DISCOVERY ISSUES

You should add the 'asciidoc' tag to your articles as Didier's has, so that readers can
discover related topics.

Didier's article shows up on the 'howtos' start page under 'Non-Categorized'. It also shows
up under the 'misc' category(perhaps that is a side affect of the author not selecting
a category?).

Your articles are in the 'HOWTO articles - Software' and the table header on that category's
landing page is incorrect: 'Overview of Slackware Administration HOWTOS'. I assume
that a site admin has to fix that problem.

It may be helpful to have 'See also' sections at the bottom of all articles like
wikipedia does.

These are not complaints, just suggestions.

Thank you all for contributing!
 
Old 12-18-2014, 11:07 AM   #15
bimboleum
Member
 
Registered: Oct 2009
Posts: 111

Rep: Reputation: 23
Interesting, veerryyyyyyy interesting!

I worked for IBM for a long time and early on in my time there I was introduced to the IBM "script" markup language for documents. It predates html but (being a tool to perform the same task) is very similar to html. The result is that I tend to write html tags directly in my notes.

Why learn yet another markup language!

Isn't life wonderful :-)

cheers
pete

pete hilton
saruman@ruvolo-hilton.org
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off



Similar Threads
Thread Thread Starter Forum Replies Last Post
Howto use a live cd with images ....mini howtos aus9 LinuxQuestions.org Member Success Stories 3 03-13-2008 09:36 AM
Installing Java on Debian ... Mini Howto rickh Debian 17 01-18-2008 10:31 PM
DISCUSSION: ssh - mini howto satinet LinuxAnswers Discussion 0 02-27-2006 02:47 PM
HostAP - very mini HOWTO on Fedora 2 SteveGodfrey Linux - Wireless Networking 5 06-21-2004 05:43 PM
pctel(789) mini HOWTO kernel() Red Hat 0 09-22-2003 10:00 PM

LinuxQuestions.org > Forums > Linux Forums > Linux - Distributions > Slackware

All times are GMT -5. The time now is 06:20 PM.

Main Menu
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Open Source Consulting | Domain Registration