Re: A very simple documentation framework
On Sat, Mar 03, 2007 at 11:16:53AM EST, ][ wrote: > On Sat, 03 Mar 2007 03:36:01 -0500, cga2000 wrote: > [..] > >> > >> AsciiDoc Markup Syntax Quick Summary > >> http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/ A bit OT .. but what is this xpt project? Apart from the AsciiDoc manuals, there tons of useful documents on this web site. > > Actually, in my setup at least, the "Dark Background" document looks > > absolutely great in a text browser such as elinks. > > Have you check it out in GUI browsers as well, for the embedded images? They look ok, but I'm used to reading docs in text-mode and I find all the different size fonts, colors, little icons, etc. distracting. > > Maybe another concern of mine is that LaTeX and DocBook are technologies > > that won't go away any time soon.. And this guarantees that both the > > time I spend rewriting my .txt documents in either of these, and the > > time spent acquiring some fluency using them is not entirely wasted. > > > > Right now, my preference would probably be DocBook over LaTeX since it > > clearly separates content and formatting... > > Seems that I didn't make it quite clear. The above "AsciiDoc Markup Syntax > Quick Summary" shows how simple it is to produce stunning effects via just > plain text. It's not really plain text. More like a cross of a simplified markup language and a word processor. ie. the "tagging" is designed in such a way as to be less obtrusive and in a sense even somewhat "wysiwg". > In fact the source (for making the html or whatever) looks > nothing like any markup language but plain text. You almost don't need to > learn anything, well I mean the markup language -- just learn how to > format your text content. In this respect, I really don't see much difference between AsciiDoc's minimal syntax and using a minimal subset of LaTeX or DocBook. There is naturally more to type, parcticularly with XML and its opening and closing tags.. but then, I type reasonably fast and I'm sure there has to be some Vim plugin that would help make life easier for me. I admit that with AsciiDoc, source files are easier to read, especially for someone unfamiliar with the syntax .. But then contrary to using a subset of something much bigger such as LaTeX or DocBook, you're bound to lose "scalability". > Further, you can produce html or DocBook/LaTeX source from AsciiDoc, and > even *nix man pages. Saw that. See below. > All in all, check out > > AsciiDoc > http://www.methods.co.nz/asciidoc/ > > and see if its simple formatting fits all your need for your simple > documentation framework, before submerging into something *much* more > complicated. If you stick with a small subset neither LaTeX nor DocBook are *that* hard to learn. My main problem, especially with DocBook, was finding exactly what debian packages I needed to build working html/pdf tool chains. > If it doesn't seem to meet all your need, I recommend to go directly to > Latex. Because the documents that you've seen on xpt.sourceforge.net and > AsciiDoc sites are actually produced by DocBook. You've lost me. Are you recommending LaTeX or DocBook? > On xpt.sourceforge.net the separated pages with TOC is produced by > DocBook (from AsciiDoc source). The single file versions are produced > directly by AsciiDoc. > > Check out the difference at > > http://xpt.sourceforge.net/techdocs/nix/asciidoc-usg/ascu03-SourceCodeHighlighting/ar01s04.html#id2497513 > > and compare with the "single file version" link from the bottom of the > page. > > If you do need Latex, then maybe the > > All You Need to Know about Latex > http://xpt.sourceforge.net/techdocs/language/latex/ > > might give you somewhat easier start. That is in fact what all I need to > know when writing my master thesis. Since I haven't found a tool that does that well, at least with my text files, I may yet invest in AsciiDoc a bit because I have numerous doc files in text format and I was wondering if it might help convert them to DocBook format. Obviously, it won't do it out of the box but I have a feeling that with minimal changes to my text files I may be able to do that. Thanks, cga -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework
On Sat, 03 Mar 2007 03:36:01 -0500, cga2000 wrote: >> Check out AsciiDoc. >> If you don't believe that everything behind it was just plain text, check >> out the >> >> AsciiDoc Markup Syntax Quick Summary >> http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/ > > Actually, in my setup at least, the "Dark Background" document looks > absolutely great in a text browser such as elinks. Have you check it out in GUI browsers as well, for the embedded images? > Maybe another concern of mine is that LaTeX and DocBook are technologies > that won't go away any time soon.. And this guarantees that both the > time I spend rewriting my .txt documents in either of these, and the > time spent acquiring some fluency using them is not entirely wasted. > > Right now, my preference would probably be DocBook over LaTeX since it > clearly separates content and formatting... Seems that I didn't make it quite clear. The above "AsciiDoc Markup Syntax Quick Summary" shows how simple it is to produce stunning effects via just plain text. In fact the source (for making the html or whatever) looks nothing like any markup language but plain text. You almost don't need to learn anything, well I mean the markup language -- just learn how to format your text content. Further, you can produce html or DocBook/LaTeX source from AsciiDoc, and even *nix man pages. All in all, check out AsciiDoc http://www.methods.co.nz/asciidoc/ and see if its simple formatting fits all your need for your simple documentation framework, before submerging into something *much* more complicated. If it doesn't seem to meet all your need, I recommend to go directly to Latex. Because the documents that you've seen on xpt.sourceforge.net and AsciiDoc sites are actually produced by DocBook. On xpt.sourceforge.net the separated pages with TOC is produced by DocBook (from AsciiDoc source). The single file versions are produced directly by AsciiDoc. Check out the difference at http://xpt.sourceforge.net/techdocs/nix/asciidoc-usg/ascu03-SourceCodeHighlighting/ar01s04.html#id2497513 and compare with the "single file version" link from the bottom of the page. If you do need Latex, then maybe the All You Need to Know about Latex http://xpt.sourceforge.net/techdocs/language/latex/ might give you somewhat easier start. That is in fact what all I need to know when writing my master thesis. HTH -- Tong (remove underscore(s) to reply) http://xpt.sf.net/techdocs/ http://xpt.sf.net/tools/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework
On Fri, Mar 02, 2007 at 10:37:52PM EST, ][ wrote: > Sorry for responding late... No problem. I'm still working on it. :-) > On Sun, 11 Feb 2007 11:05:07 -0500, Douglas Allan Tutty wrote: > > On Sun, Feb 11, 2007 at 06:11:58AM -0500, cga2000 wrote: > >> So far my personal doc system amounts to a patchwork of notes and > >> cheat sheets in ascii files that I grep when I need to find some piece > >> of information or other. > >> > >> I would like to switch to something a little more ambitious where I > >> would be able to generate my docs in the usual popular formats, namely > >> pdf, html, ps, txt, and possibly dvi. > > I asked something similar a couple of months ago and the concensus was > > either LaTex or DocBook. > > No, LaTex or DocBook would be too much over kill for simple documentation, > though I'm very found of LaTex myself. You're right, but it's difficult to resist learning at least the basics of LaTeX and DocBook. The risk, naturally, is that trying to kill two birds with one stone I might miss both (writing the doc and learning the documentation tools) .. and end up empty-handed. > Check out AsciiDoc. > Would something like this (AsciiDoc sample output) > http://xpt.sourceforge.net/techdocs/misc/ce01-DarkBackgroundIsGoodForYou/ > be good enough? It fulfills all your requirement, but is even more simpler. Definitely. I would add that due to their complexity, achieving the same quality going down the LaTeX or the DocBook toolchains is probably not going to be trivial. A more subtle risk is possibly that considering that these two are such large complex products and that since I lack the technical proficiency (and likely the time to acquire it) .. I may have to stick to a such a small subset of their respective capabilities that I would end up limiting myself as a "writer". What I mean is that for instance, I might want to present a given topic in a certain way but end up doing differently only because I'd start thinking that it would take me days (or weeks..) to figure out how to do it. > If you don't believe that everything behind it was just plain text, check > out the > > AsciiDoc Markup Syntax Quick Summary > http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/ Actually, in my setup at least, the "Dark Background" document looks absolutely great in a text browser such as elinks. :-) Maybe another concern of mine is that LaTeX and DocBook are technologies that won't go away any time soon.. And this guarantees that both the time I spend rewriting my .txt documents in either of these, and the time spent acquiring some fluency using them is not entirely wasted. Right now, my preference would probably be DocBook over LaTeX since it clearly separates content and formatting. In my case it's not just a matter of DocBook doing the "right" thing. An additional incentive is that as long as I can find suitable stylesheets, I only need to become fluent with a dozen or so xml tags to get started and the transformation tools will take care of everything else for me. I also saw somewhere that there seems to exist a simplified version of DocBook. I know nothing about its current status, but I should probably take a look and see it might do anything for me .. Lastly, I'm also curious of DocBook's capabilities as far as providing a framework that might (?) help locate information in what would amount to a "documentation database". Here again, recursive grep's of my text files usually works where my personal docs are concerned .. but in terms of "concept", it's clearly not a very satisfying approach. Maybe I'm more interested in documentation technology than the drudgery of writing and maintaining documents. :-) In any case, thanks much for your comments. Thanks, cga -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework
Sorry for responding late... On Sun, 11 Feb 2007 11:05:07 -0500, Douglas Allan Tutty wrote: > On Sun, Feb 11, 2007 at 06:11:58AM -0500, cga2000 wrote: >> So far my personal doc system amounts to a patchwork of notes and >> cheat sheets in ascii files that I grep when I need to find some piece >> of information or other. >> >> I would like to switch to something a little more ambitious where I >> would be able to generate my docs in the usual popular formats, namely >> pdf, html, ps, txt, and possibly dvi. >> >> In terms of document structure, my needs are very basic: >> >> == >> This is the main title of my document >> 1. Chapter 1. >> 1.1 Paragraph 1. >> This is a list >> 1. list item 1 >> 2. list item 2 >> blurb blurb blurb blurb blurb blurb blurb .. > [snip standard technical report] >> >> I am not concerned about typesetting .. the only requirement is that the >> contents of tables and samples should materialize in a non-proportional >> font in order to be legible. >> >> My only other requirement is that this "documentation system" should not >> require the implementation of complex gui tools. I want to do it in vim >> and use command line tools to generate the various formats. > > I asked something similar a couple of months ago and the concensus was > either LaTex or DocBook. No, LaTex or DocBook would be too much over kill for simple documentation, though I'm very found of LaTex myself. Check out AsciiDoc. Would something like this (AsciiDoc sample output) http://xpt.sourceforge.net/techdocs/misc/ce01-DarkBackgroundIsGoodForYou/ be good enough? It fulfills all your requirement, but is even more simpler. If you don't believe that everything behind it was just plain text, check out the AsciiDoc Markup Syntax Quick Summary http://xpt.sourceforge.net/techdocs/nix/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/ HTH -- Tong (remove underscore(s) to reply) http://xpt.sf.net/techdocs/ http://xpt.sf.net/tools/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
On Tue, Feb 13, 2007 at 06:20:24AM EST, Chris Lale wrote: > cga2000 wrote: > >So far my personal doc system amounts to a patchwork of notes and > >cheat sheets in ascii files that I grep when I need to find some piece > >of information or other. > > > >I would like to switch to something a little more ambitious where I > >would be able to generate my docs in the usual popular formats, namely > >pdf, html, ps, txt, and possibly dvi. > > > > > [...] > > GUI: LyX is a WYSIWYM front end to Latex. > > CLI: DocBook and Sgmltools-lite might meet some of your needs. > > For something really simple try Zim - a desktop wiki that stores content > as text files and can export to HTML. Thanks to all. I won't have the time to review your solutions until the weekend -- with President's Day we get three of them over here .. :-) .. I have given it a bit more thought and eventually I will probably choose a solution that is also "scalable". What I mean by that is something that can do the very simple things I tried to illustrate in my original post .. but to which I can add more features as I go along. I already know how to do basic stuff in LaTeX and since it looks like there are utilities to generate just about any format from .tex files .. I may stick with that for now. But I will also investigate the DocBook/xml solution .. I have a feeling that these days, "XML" would look considerably more attractive than LaTeX on my resumé .. :-) Thanks, cga -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
cga2000 wrote: So far my personal doc system amounts to a patchwork of notes and cheat sheets in ascii files that I grep when I need to find some piece of information or other. I would like to switch to something a little more ambitious where I would be able to generate my docs in the usual popular formats, namely pdf, html, ps, txt, and possibly dvi. [...] GUI: LyX is a WYSIWYM front end to Latex. CLI: DocBook and Sgmltools-lite might meet some of your needs. For something really simple try Zim - a desktop wiki that stores content as text files and can export to HTML. -- Chris. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
On Sun, Feb 11, 2007 at 11:05:07AM -0500, Douglas Allan Tutty wrote: > If one were using a GUI it would probably be a possibility for me, but > there's a lot more typing for XML tags than there are in Tex. Tex is > also very similar to Lout (or rather, Lout is rather similar to Tex) so > that eases my learning curve. That is why you have key bindings. e.g. in your .vimrc: map i\documentclass[a4paper]{article} -- Chris. == Don't forget to check that your /etc/apt/sources.lst entries point to etch and not testing, otherwise you may end up with a broken system once etch goes stable. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
Douglas Allan Tutty wrote: On Sun, Feb 11, 2007 at 06:11:58AM -0500, cga2000 wrote: So far my personal doc system amounts to a patchwork of notes and cheat sheets in ascii files that I grep when I need to find some piece of information or other. I would like to switch to something a little more ambitious where I would be able to generate my docs in the usual popular formats, namely pdf, html, ps, txt, and possibly dvi. In terms of document structure, my needs are very basic: == This is the main title of my document 1. Chapter 1. 1.1 Paragraph 1. This is a list 1. list item 1 2. list item 2 blurb blurb blurb blurb blurb blurb blurb .. [snip standard technical report] I am not concerned about typesetting .. the only requirement is that the contents of tables and samples should materialize in a non-proportional font in order to be legible. My only other requirement is that this "documentation system" should not require the implementation of complex gui tools. I want to do it in vim and use command line tools to generate the various formats. Hi cga, I asked something similar a couple of months ago and the concensus was either LaTex or DocBook. I have been using LaTex for years because its use was easy after the IBM tools for printing docs. I also use hyperlatex to create html pages with LaTex: http://packages.debian.org/unstable/tex/hyperlatex Hugo -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
On Sunday 11 February 2007 09:11, cga2000 wrote: > So far my personal doc system amounts to a patchwork of notes and > cheat sheets in ascii files that I grep when I need to find some piece > of information or other. > > I would like to switch to something a little more ambitious where I > would be able to generate my docs in the usual popular formats, namely > pdf, html, ps, txt, and possibly dvi. Take a look at http://txt2tags.sourceforge.net/features.html apt-cache show txt2tags -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
"cga2000" <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] So far my personal doc system amounts to a patchwork of notes and cheat sheets in ascii files that I grep when I need to find some piece of information or other. I would like to switch to something a little more ambitious where I would be able to generate my docs in the usual popular formats, namely pdf, html, ps, txt, and possibly dvi. [snip] I am not concerned about typesetting .. the only requirement is that the contents of tables and samples should materialize in a non-proportional font in order to be legible. My only other requirement is that this "documentation system" should not require the implementation of complex gui tools. I want to do it in vim and use command line tools to generate the various formats. Would anyone have any recommendations as to how I should proceed? I'm pretty sure what you want is ReStructuredText. It is developed for python. It uses a syntax VERY similar to what you showed. It does do proper formating. It is also designed such that it is easy to read the original text files. To avoid having email corrupt my example file I have posted it at http://monoport.com/1758 The example file does not include the line number. If you try to copy the text you will notice that the line numbers are not copied. That is correct. Anyway, to view the example output, copy that file and paste it into the text box on http://www.hosting4u.cz/jbar/rest/rest.html and push the render buton. I think you will find that the HTML output is very nice considering how simple the syntax is. If you are interested I suggest reading http://docutils.sourceforge.net/docs/user/rst/quickstart.html Which will explain a few more features. The main page to find more information is http://docutils.sourceforge.net/rst.html If you have any questions, feel free to contact me off list. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
cga2000 writes: > So far my personal doc system amounts to a patchwork of notes and > cheat sheets in ascii files that I grep when I need to find some piece > of information or other. > I would like to switch to something a little more ambitious where I > would be able to generate my docs in the usual popular formats, namely > pdf, html, ps, txt, and possibly dvi. I use the following packages for that: ii docbookstandard SGML representation system for tech... ii docbook-dsssl modular DocBook DSSSL stylesheets, for print... ii docbook-utils Convert Docbook files to other formats (HTML... -- -- Jhair -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
On Sun, Feb 11, 2007 at 06:11:58AM -0500, cga2000 wrote: > So far my personal doc system amounts to a patchwork of notes and > cheat sheets in ascii files that I grep when I need to find some piece > of information or other. > > I would like to switch to something a little more ambitious where I > would be able to generate my docs in the usual popular formats, namely > pdf, html, ps, txt, and possibly dvi. > > In terms of document structure, my needs are very basic: > > == > This is the main title of my document > 1. Chapter 1. > 1.1 Paragraph 1. > This is a list > 1. list item 1 > 2. list item 2 > blurb blurb blurb blurb blurb blurb blurb .. [snip standard technical report] > > I am not concerned about typesetting .. the only requirement is that the > contents of tables and samples should materialize in a non-proportional > font in order to be legible. > > My only other requirement is that this "documentation system" should not > require the implementation of complex gui tools. I want to do it in vim > and use command line tools to generate the various formats. > Hi cga, I asked something similar a couple of months ago and the concensus was either LaTex or DocBook. I don't like GUI tools. For years I've been using Lout but it only puts out to text, ps, and pdf. I've finally bitten the bullet and am looking at LaTex. It will do whatever output format you like either with a dvi2* or a tex2* type processor. The documentation is great except that it comes in tex and ps. I suppose one could convert the tex to html and make a system of that. I have also looked at DocBook. It is in transition from SGML to XML. The DocBook-Definitive Guide (docbook-dg) isn't packaged for Etch yet and previous docs only delt with SGML. If one were using a GUI it would probably be a possibility for me, but there's a lot more typing for XML tags than there are in Tex. Tex is also very similar to Lout (or rather, Lout is rather similar to Tex) so that eases my learning curve. I've been looking at this in relation to my NoviceDoc project and I'm leaning toward LaTex. LaTex files can also be converted to DocBook. I know that most of LaTex is focused on typesetting so you could think it is overkill, but to me it is the easiest to implement even to put out html (unless you _only_ want html, then I suppose you could just learn html.) Doug. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
Re: A very simple documentation framework.
2007/2/11, cga2000 <[EMAIL PROTECTED]>: I would like to switch to something a little more ambitious where I would be able to generate my docs in the usual popular formats, namely pdf, html, ps, txt, and possibly dvi. Hi, LaTeX [1] is your friend. :) [1] http://www.latex-project.org/ Best regards, Sergio Cuellar -- "Meine Hoffnung soll mich leiten Durch die Tage ohne Dich Und die Liebe soll mich tragen Wenn der Schmerz die Hoffnung bricht" -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
A very simple documentation framework.
So far my personal doc system amounts to a patchwork of notes and cheat sheets in ascii files that I grep when I need to find some piece of information or other. I would like to switch to something a little more ambitious where I would be able to generate my docs in the usual popular formats, namely pdf, html, ps, txt, and possibly dvi. In terms of document structure, my needs are very basic: == This is the main title of my document 1. Chapter 1. 1.1 Paragraph 1. This is a list 1. list item 1 2. list item 2 blurb blurb blurb blurb blurb blurb blurb .. +---+ | this is a config file sample | +---+ blurb blurb blurb blurb blurb blurb blurb .. +---+ | this is a table | +-+---+-+ | | | | | | | | | | | | +-+---+-+ blurb blurb blurb blurb blurb blurb blurb .. 1.2 Paragraph 2 .. ... == And that's it. I am not concerned about typesetting .. the only requirement is that the contents of tables and samples should materialize in a non-proportional font in order to be legible. My only other requirement is that this "documentation system" should not require the implementation of complex gui tools. I want to do it in vim and use command line tools to generate the various formats. Would anyone have any recommendations as to how I should proceed? Thanks, cga -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]