What's the best way to author man pages? Should I write using the standard man macros, or is there some clever package available now that takes some kind of XML-ified source and can output man pages, HTML, ASCII, and what not?
Thanks
I have previously used the GNU version of nroff called groff to write man pages.
Nice intro article on it here:
http://www.linuxjournal.com/article/1158
Doxygen is what you are looking for.
Keep in mind that it is designed to document source code but you could easily adapt it.
It can generate html, pdf, and latex documentation too.
If you are looking at writing once and generating different output formats such as manpages, HTML, plain txt, or even PDF, then docbook should work best.
A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly.
For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown like syntax. I am extremely happy with it.
atinout(1) -- Send AT commands to modem, capturing the response
===============================================================
## SYNOPSIS
`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>
## DESCRIPTION
**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...
see the whole page here.
Related
I'd like to use emacs in some kind of batch mode to just render a file with syntax highlighting and exit. Specifically, I want to dump the fontified buffer with ANSI escape codes so that it shows up reasonably syntax-highlighted on my terminal. Is there any way to do this?
The ansi-lpr.el library seems to be kind of along the lines of what I want, but the output isn't colorified. I can't figure out how to get over that final hurdle — there are a lot of modules to digest ANSI escape codes into Emacs text properties (e.g. ansi-color.el) but I haven't found anything that does the reverse. If anyone can point me to something that does, I think I can piece together the rest.
Alternatively, I've seen some hacky approaches like this answer (using script and capturing the output) but in my experiments that approach has seemed unlikely to be fruitful — you get tons of undesirable control sequences mixed in with the highlighted text.
The overarching motivation here is to use emacs in a $LESSOPEN pipe to get syntax highlighting when I page files. In case you're going to say it, I've tried and "just page files in Emacs" is not acceptable for me.
I'm glad to announce a new package, e2ansi, that (hopefully) does what you asked for.
The package provides a command-line tool e2ansi-cat that starts Emacs in batch mode, opens files, syntax highlight them (using font-lock), and creates ANSI-colored versions of the syntax highlighted files.
You can integrate this into less by setting the following variables to, for example:
export "LESSOPEN=|emacs --batch -Q -l ~/.emacs -l bin/e2ansi-cat %s"
export "LESS=-R"
export MORE=$LESS
The end result looks like the following:
You can vary the colors and attributes like bold, underline, and
italics by using a suitable Emacs theme.
The e2ansi package is located at https://github.com/Lindydancer/e2ansi
Personal note
I would like to thank you for posting this question, it directly inspired me to write e2ansi.
Is there for doxygen is a more lightweight HTML backend, which does not fill the page with tons of divs and tables? When looking at the css file, the output seems quite bloated. It possible to write another backend. I ask if there already exists one.
Reasons why I need this
It makes it easier to integrate the dox with the rest of the website.
I use hyphenate.js to make my "Related Pages" look good. But that script needs to know which tags it should use. This is much easier with less bloat markup.
Doxygen lacks complete documentation on how the output markup making reverse engineering using Firefox Web Developer tool necessary to modify the 1k lines CSS file. Less bloat markup makes less need for documentation, and it makes documentation more easy for Dimitri to maintain.
Less bloat markup makes the pages more portable.
With doxygen you can export your data in html format, tex format, XML (which you can later parse as you want), RTF, Man pages or Docbook.
The html output supports a custom header, footer and stylesheet (CSS) with the HTML_STYLESHEET attribute which might be what you want. You can rewrite those and adjust the output as you like.
If nothing satisfies you, then you might start thinking manually parsing one of the outputs above with your own scripting language and generate the desired format by yourself (if that suits you) or taking over control of the output generation directly via doxygen sources (https://github.com/doxygen/)
Sources: http://www.doxygen.nl/manual/output.html
What you need to do really depends on exactly what you want to end up with.
There are 'Input Filters', eg: ftp://ftp.rsa.com/pub/dsg/public/doxygen/doxyfilt.pl and 'Output Filters, eg: http://www.bigsister.ch/doxygenfilter/doxygenfilter.html . Writing a customized Filter should do exactly what you want. Using existing Code and putting up with it's limitations will be faster and may provide ideas for writing your own Program (if you wish to do so).
You can try this Website http://www.dirtymarkup.com/ with the output that you object to and see if one of the Tools it suggests will "clean" the Code up enough to your liking without removing too much functionality (IE: the ability to click on Links and expand / contract Sections).
If you really want it 'raw' try HTML2Text https://pypi.python.org/pypi/html2text and then you can 'wrestle it back' with Text2HTML http://txt2html.sourceforge.net/ . That will strip it bare and yet give you back some minimal HTML functionality (preserve Linking).
There are MANY 'HTML <-> Text' converters, in many Languages, use a Search Engine to find your own Source; one that is most suitable for you.
Here is a List of Tools from a reputable Site: http://www.w3.org/Tools/html2things.html .
Here is an List of alternates to convert Languages to HTML: http://www.w3.org/Tools/Prog_lang_filters.html . More Info here: http://www.w3.org/Tools/Filters.html .
As I understood it "javadoc" is the name of the tool that generates html-documentation which also goes by the name javadoc. Atleast that is how I've been using the words..
But what is the generated output of the tool doxygen called? Doxygen-doc? doxy-doc? or maybe something else?
(Question in c++ context, if it matters)
Separate the tools from the output format.
Javadoc is a markup system. I think it is incorrect to call its html output (or any other output) "javadoc". The same way as you would not call a web page styled in Word "Word".
Similarly, Doxygen is also a markup system. It does not have its own documentation output type. Its 'types' are the output types it supports, that is: HTML, Latex, Man pages, RTF and more. See the full list.
You mention C++. Doxygen supports "C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.
See Overview.
Short answer: "Design Documentation"
It's not a file format, it's a type of document that can be in any format. Usually html if you used Doxygen to create it.
I wanted to ask if there are any features (or add-ons) for Doxygen to measure the documentation coverage via command line. I already know that I can set up Doxygen to write undocumented elements as warnings into a log file, but to fully evaluate the documentation coverage from that, I'd need to write my own warning log parser. Was something like this done already or is there an even easier way I couldn't find? Is there any add-on I could check out for this?
Thank you.
I don't know anything that can give documentation coverage for doxygen, but a quick search gives 2 interesting results : https://github.com/alobbs/doxy-coverage (require xml output for doxygen) and http://jessevdk.github.io/cldoc/ (alternative for c++ projects?)
There is coverxygen which is using the same idea as alobbs/doxy-coverage (uses xml output of Doxygen) but provides more options (for example, filter by access specifier).
Disclaimer: I am contributing to that project.
Most PHP Developers are likely familar with the Syntax Highlighter called "GeSHi", which takes code, highlights it, with the use of HTML and CSS:
include('geshi.php');
$source = 'echo "hello, world!";
$language = 'php';
$path = 'geshi/';
$geshi = new GeSHi($source, $language, $path);
echo $geshi->parse_code();
GeSHi Supports a wide range of languages.
I wonder, is there a similar Module for Perl?
Perl has a port of Kate highlighting system: Syntax::Highlight::Engine::Kate which seems to be somewhat close to what you need. It appears to be part of Padre.
You also have an option of HTML client side highlighters (logic is obviously JS), such as Google's code prettifyer
Two good lists of syntax highlighting engines are:
Wiki syntax highlighting article - among the ones it lists, the Perl ports/APIs seem to exist for Kate and Colorer (Syntax::Highlight::Universal)
This very good review of HTML syntax highlighters, which contains a lot of client-side ones such as SHJS and many others.
Please be aware that NONE of those generic highlighters work "100% correctly", the way the syntax highlighters work in good IDEs, because they use regular expressions for approximate parsing instead of lexers for actual language grammar parsing. More details on the Wiki
You can also consider this for client side syntax highlighting.
http://alexgorbatchev.com/SyntaxHighlighter/
I have had some very good results with the PPI::HTML package. It uses PPI to parse the Perl before converting the text to HTML.
Pure Perl: Syntax::Highlight::Engine::Kate (there is Kate plugin for Padre IDE).
Wrappers for C libraries: Syntax::Highlight::Universal, Syntax::SourceHighlight.
Using external tools: Text::VimColor, Text::EmacsColor.
Also there are many one-language highlighters on CPAN.
You can always write a small php script to make GeSHi usable from command line and then call it within your perl script.
I did this for gitweb so I could leave svn (and websvn) behind for good.
My search brought me here, because I was looking for a 'Perl Syntax Highlighter' like the title said and not an general highlighter implemented in Perl.
To highlight only Perl, perltidy --html can be used. It belongs to the Perl::Tidy distribution the main module can be imported and used without spawning a process.
https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy#HTML-OPTIONS
So not what the OP actually wanted to know, but hopefully of help for others coming here for the same reasons like me ... :)