Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
What is a good style guide for formatting documents, outlines and procedure descriptions using ASCII text only?
I am thinking of a set of rules for using capitalization, 'underlines" (with '-' or '=' on the line below), indentation, etc to help visually organize text into sections, subsections, etc.
Guide supported by vi would be especially nice.
Consider using Markdown or MultiMarkdown for formatting your plain-text documents. There is a vim Markdown syntax plugin available, and it's widely used on Stack Overflow and GitHub:
https://stackoverflow.com/editing-help
https://help.github.com/articles/github-flavored-markdown
Beside Markdown and reStructuredText there exists also AsciiDoc, which is more powerful than Markdown: There are f.ex. plugins that define how you can write diagrams in ASCII Text.
AsciiDoc is less popular than Markdown, but after Github supports now AsciiDoc too it will get more popular.
All these three text formats also have vim plugins.
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
I've got an NSIS script that is a couple thousand lines and not properly indented making the script difficult to read. Is there a way to format NSIS script or at the minimum be able to indent the Ifs and Endifs sections? There's plenty of online script formatters for HTML, Javascript, XML, etc.
Notepad++ does an excellent job of supporting the NSI code conventions straight out of the box.
I've used EclipseNSIS for working with NSIS before; it at least uses syntax highlighting, which is nice.
Atom Editor is also really nice for NSIS, and it has some packages you can add on to make it easier to work on NSIS scripts.
I don't think I ever found anything to prettify or format the script, unfortunately, but that may now be a part of either Atom or EclipseNSIS, I'm not sure.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
I'm currently trying to find a documentation (user guide) system that would have following features:
documentation files in text mode (so svn could diff/merge it)
possibility to use images, table, cross-references and table of
contents
export to pdf (or .doc/.odt) that would support cross-references
I tried markdown for documentation source files and pandoc for pdf export but markdown does not support tables.
I really appreciate any help you can provide.
We use Sphinx for this scenario.
It can generate html, pdf and some other formats from reStructuredText Files.
And have a look at list-table when you want to add complex tables.
I use the TeX for electonic and printable documentation
https://tex.stackexchange.com/
https://en.wikipedia.org/wiki/TeX
Probably the most commonly used solution set for documentation is XML in Docbook or DITA. You can certainly manage those in SVN as well as perform diffs. They both provide processing toolchains with many output types include PDF through XSL FO.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Is there a cheatsheet that compares the usage of Markdown with Restructure? With this, I could learn rst faster if I already knew Markdown. I tried google for it but haven't found one..
A small comparsion from a lot lightweight markup language syntaxs can be found on Wikipedia.
There is also a Gist document about the common markup between the two languages.
You can use Pandoc to convert your existing Markdown to reST or the other way around.
There are a lot of different Markdown dialects, so it may be difficult to compare the syntax with reST.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I've use javadoc, as well as a variety of different XML based doc-generation systems. Javadoc is fine, XML based doc-generators are hideous, with the XML getting all over the comments and turning the comments into soup.
I've looked at markdown, and the fact that it is easily parseable into structured data but also super human-readable would make it perfect for in-code comments, where the readability of both the docs and the plaintext is of utmost importance.
Are there any markdown based doc-generators out there already? Is there any reason why it wouldn't work which I don't know of?
There exits some Markdown-Doclets (f.ex. http://www.richardnichols.net/open-source/markdown-doclet/ ) which can be used with JavaDoc.
Maybe you are also interested in the famous doxygen tool. It doesn't use Markdown but the format is very similar to it (f. ex. unordered lists with - etc.).
You may try mdoc to generate Markdown based documentation. It reads all the .md files and produces HTML based documentation. It also creates a TOC. Check it out.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 years ago.
Improve this question
I'm a jack-of-all-trades-master-of-none programmer and as I jump around languages, quality consistent documentation is becoming more and more important to me. I've recently been using Doxygen, but Wikipedia reveals the usual ridiculous list of similar frameworks.
What is your favorite documentation generator and why? (Vote where you agree to keep it tidy!)
I use different files written in MediaWiki MarkUp, since this is easy to learn for everyone. I convert this to HTML and a CHM file, and to LaTeX for the PDF documentation.
This was the most painless way for me to generate Online documentation AND printable documentation in one strike with a simple way of input.
The tools I use are org.eclipse.mylyn.wikitext with a custom DocumentBuilder for LaTeX, the Microsoft Help compiler (which sadly only runs on windows), and a LaTeX distribution.
EDIT: I managed to get the Microsoft Help compiler running with Wine, so my Linux build server is now able to create the whole documentation automatically.