asciidoc mini howto
2 Attachment(s)
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 \ EDIT: BTW, for those wondering, the mini howto is in the attached files. |
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.
|
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 |
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. |
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. |
Quote:
asciidoc has become too bloated for my taste, so i use markdown for technical papers. |
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 |
Quote:
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. |
Quote:
|
Quote:
|
Quote:
EDIT: To set the record straight, Didier had already written an article about asciidoc in slackdocs :-) |
Quote:
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? |
Quote:
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. |
Quote:
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! |
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 |
All times are GMT -5. The time now is 04:39 PM. |