DaemonForums  

Go Back   DaemonForums > Miscellaneous > General software and network

General software and network General OS-independent software and network questions, X11, MTA, routing, etc.

Reply
 
Thread Tools Display Modes
  #1   (View Single Post)  
Old 5th January 2016
J65nko J65nko is offline
Administrator
 
Join Date: May 2008
Location: Budel - the Netherlands
Posts: 3,503
Default Lightweight markup languages

I need to write some documentation for some Perl scripts. The command line options, the format of the initialization files, the networking requirements, the setup and running a test to verify the working.

What is your experience with any of the so-called 'Lightweight markup languages'?

These are the ones I heard of:
Any recommendation?
__________________
You don't need to be a genius to debug a pf.conf firewall ruleset, you just need the guts to run tcpdump

Last edited by J65nko; 5th January 2016 at 03:22 AM. Reason: fixed typo
Reply With Quote
  #2   (View Single Post)  
Old 5th January 2016
Carpetsmoker's Avatar
Carpetsmoker Carpetsmoker is offline
Real Name: Martin
Old man from scene 24
 
Join Date: Apr 2008
Location: Dutchman living in the UK
Posts: 2,196
Default

I use Markdown; not necessarily because it's the best, but because that's the closest thing to "standard" there is today. Stack Overflow, GitHub, BitBucket, and reddit use it.
I find that switching markup languages is annoying as half the time you're typing in the wrong language. It's mostly intuitive, but there are some annoyances (like different behaviours across implementations).

I used txt2tags for a while (many of my posts in "Guides" are written by it), but switched to markdown as I didn't want to change between three markup languages (Markdown, txt2tags, Wiki). It hasn't received updates since 2010, so it seems rather dead. The chief advantage of markdown is increased flexibility, although depending on which markdown converted you use, this can also be achieved with Markdown.

reStructuredText and Textile are two other alternatives. I never used either.
__________________
UNIX was not designed to stop you from doing stupid things, because that would also stop you from doing clever things.
Reply With Quote
  #3   (View Single Post)  
Old 5th January 2016
Oko's Avatar
Oko Oko is offline
Rc.conf Instructor
 
Join Date: May 2008
Location: Kosovo, Serbia
Posts: 1,101
Default

I use occasionally txt2tags when a quick html output is required. Normally I use TeX for writing papers. I would suggest you also check Pandoc which is written in Haskell. You can install it on OpenBSD using Cabal Haskell package manager since Pandoc is not in ports. Cabal is in ports and works very well on OpenBSD. Pandoc converts multiple documen (light mark up) formats into each other. For man pages I would use mandoc and mdoc macros written by Kristaps Dzonsons. Unlike Groff it supports html, PosrScript outputs and of course has beautiful Ascii output. Of course mandoc just like Groff and TeX is full blown text typing system and it doesn't have light learning curve. I will finish this post with the remark that TeX (my bread and butter) is not designed for Ascii or even HTML output. Man pages is one of those rare instances (besides Music for which I use LilyPond) where TeX is not a right tool for the job.

Last edited by Oko; 5th January 2016 at 08:29 PM. Reason: Original post was typed on Android phone and suffered numerous typographic errors.
Reply With Quote
  #4   (View Single Post)  
Old 5th January 2016
J65nko J65nko is offline
Administrator
 
Join Date: May 2008
Location: Budel - the Netherlands
Posts: 3,503
Default

Thanks to both of your for the feedback and suggestions.

At this moment I am writing a small test file in AsciiDoc, because it claims to be "semantically equivalent to DocBook XML". Many years ago I spent some time with DocBook, but although I liked it's possibilities, I found it too much of a hassle to use.

Pandoc looks very interesting. I will definitely have a look at it.
__________________
You don't need to be a genius to debug a pf.conf firewall ruleset, you just need the guts to run tcpdump
Reply With Quote
Reply

Tags
asciidoc, markdown, markup language, txt2tags

Thread Tools
Display Modes

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 On
HTML code is Off

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
Package lists/Config files for Lightweight Desktop/Funding Option shep Feedback and Suggestions 1 16th December 2013 07:24 PM
Dynamic Languages Conference: it's an Edinburgh thing J65nko News 0 15th August 2011 03:19 PM
brief incomplete and mostly wrong history of programming languages TerryP Off-Topic 2 9th May 2009 11:05 PM
Need a lightweight browser to replace Fx3 TerryP General software and network 15 12th February 2009 10:45 PM


All times are GMT. The time now is 03:26 AM.


Powered by vBulletin® Version 3.8.4
Copyright ©2000 - 2017, Jelsoft Enterprises Ltd.
Content copyright © 2007-2010, the authors
Daemon image copyright ©1988, Marshall Kirk McKusick