[armedbear-devel] Manual format
Greetings, I was looking at the ABCL manual for ABCL 1.0 under the 'manual' directory. I noticed that it is in LaTeX format. I have been using TeX, LaTeX and Texinfo for many years. Among many other things, I have written two longish user manuals in Texinfo. They are located (including source) at: http://blake.mcbride.name/software/dynace/downloads.html under the 'manual' directory. With the experience I've had with TeX, LaTeX, and Texinfo, I feel very strongly that these are unbelievably great tools, and, in fact, the right tools for the job. However, I also feel strongly that Texinfo is the better format for the particular task of a manual on ABCL. I use LaTeX pretty often, but I have found Texinfo better suited for user manuals of computer topics for several reasons. First, the macros defined are more natural for the topic. Second, Texinfo supplies much better index creation tools for functions, variables, classes, etc.. Lastly, if you use Texinfo, you get online documentation for free! Texinfo is specifically designed for exactly this kind of technical document. LaTeX is equally good, but at writing non-technical books. Latex is not a natural fit for technical documents in my opinion. So, in conclusion: 1. I recommend switching to Texinfo. It would be especially easy at this early juncture. 2. The manuals I wrote come out, IMO, nicely. These documents could be used as templates. 3. My time is a real problem but I think I can convert the existing document so that you'd have it all setup to continue with if that is desired. I welcome your thoughts. Blake McBride
On Oct 22, 2011, at 04:16 , Blake McBride wrote:
Greetings,
I was looking at the ABCL manual for ABCL 1.0 under the 'manual' directory. I noticed that it is in LaTeX format. I have been using TeX, LaTeX and Texinfo for many years. Among many other things, I have written two longish user manuals in Texinfo. They are located (including source) at:
http://blake.mcbride.name/software/dynace/downloads.html
under the 'manual' directory. With the experience I've had with TeX, LaTeX, and Texinfo, I feel very strongly that these are unbelievably great tools, and, in fact, the right tools for the job. However, I also feel strongly that Texinfo is the better format for the particular task of a manual on ABCL. I use LaTeX pretty often, but I have found Texinfo better suited for user manuals of computer topics for several reasons. First, the macros defined are more natural for the topic. Second, Texinfo supplies much better index creation tools for functions, variables, classes, etc.. Lastly, if you use Texinfo, you get online documentation for free! Texinfo is specifically designed for exactly this kind of technical document. LaTeX is equally good, but at writing non-technical books. Latex is not a natural fit for technical documents in my opinion.
So, in conclusion:
1. I recommend switching to Texinfo. It would be especially easy at this early juncture.
2. The manuals I wrote come out, IMO, nicely. These documents could be used as templates.
3. My time is a real problem but I think I can convert the existing document so that you'd have it all setup to continue with if that is desired.
I welcome your thoughts.
I deliberately chose LaTeX over Texinfo after considering the arguments you mention. That after two manuals, you would still recommend Texinfo over LaTeX is another opinion to consider. To recap my arguments: 1. One can always create a simplified "domain specific" macro layer to separate markup from presentation. 'abel.sty' starts to do that for source listings. 2. I want to be able to include pictures and tables, dammit! 3. I find all the Texinfo to HTML conversion tools so aesthetically challenged that I am willing to write my own translator out of "ABCL" tex (i.e. that defined in abel.sty) to HTML. 4. I want to be able to fiddle the printed layout at a fundamental level I guess we're gonna need to discuss this a bit, Mark
Nothing is perfect, but I thought Texinfo was better suited to the task, easier to use, and good enough. I'm not stuck on it though. (The online ability I was referring to was using 'info' rather than an html converter.) Thanks. Blake On Sat, Oct 22, 2011 at 2:21 AM, Mark Evenson <evenson.not.org@gmail.com> wrote:
On Oct 22, 2011, at 04:16 , Blake McBride wrote:
Greetings,
I was looking at the ABCL manual for ABCL 1.0 under the 'manual' directory. I noticed that it is in LaTeX format. I have been using TeX, LaTeX and Texinfo for many years. Among many other things, I have written two longish user manuals in Texinfo. They are located (including source) at:
http://blake.mcbride.name/software/dynace/downloads.html
under the 'manual' directory. With the experience I've had with TeX, LaTeX, and Texinfo, I feel very strongly that these are unbelievably great tools, and, in fact, the right tools for the job. However, I also feel strongly that Texinfo is the better format for the particular task of a manual on ABCL. I use LaTeX pretty often, but I have found Texinfo better suited for user manuals of computer topics for several reasons. First, the macros defined are more natural for the topic. Second, Texinfo supplies much better index creation tools for functions, variables, classes, etc.. Lastly, if you use Texinfo, you get online documentation for free! Texinfo is specifically designed for exactly this kind of technical document. LaTeX is equally good, but at writing non-technical books. Latex is not a natural fit for technical documents in my opinion.
So, in conclusion:
1. I recommend switching to Texinfo. It would be especially easy at this early juncture.
2. The manuals I wrote come out, IMO, nicely. These documents could be used as templates.
3. My time is a real problem but I think I can convert the existing document so that you'd have it all setup to continue with if that is desired.
I welcome your thoughts.
I deliberately chose LaTeX over Texinfo after considering the arguments you mention. That after two manuals, you would still recommend Texinfo over LaTeX is another opinion to consider.
To recap my arguments:
1. One can always create a simplified "domain specific" macro layer to separate markup from presentation. 'abel.sty' starts to do that for source listings.
2. I want to be able to include pictures and tables, dammit!
3. I find all the Texinfo to HTML conversion tools so aesthetically challenged that I am willing to write my own translator out of "ABCL" tex (i.e. that defined in abel.sty) to HTML.
4. I want to be able to fiddle the printed layout at a fundamental level
I guess we're gonna need to discuss this a bit, Mark
to revive an older thread... Mark Evenson writes:
On Oct 22, 2011, at 04:16 , Blake McBride wrote:
[...] So, in conclusion:
1. I recommend switching to Texinfo. It would be especially easy at this early juncture.
I deliberately chose LaTeX over Texinfo after considering the arguments you mention. That after two manuals, you would still recommend Texinfo over LaTeX is another opinion to consider.
To recap my arguments:
1. One can always create a simplified "domain specific" macro layer to separate markup from presentation. 'abel.sty' starts to do that for source listings.
I would also prefer the Texinfo format, if only for the ease of accessing info files from Emacs. There are also tools used by other lisp projects, such as stumpwm, to extract documentation from the docstrings and insert them into the documentation.
2. I want to be able to include pictures and tables, dammit!
Texinfo does images and tables. See (Info-goto-node "(texinfo) Images") and (Info-goto-node "(texinfo) Lists and Tables")
3. I find all the Texinfo to HTML conversion tools so aesthetically challenged that I am willing to write my own translator out of "ABCL" tex (i.e. that defined in abel.sty) to HTML.
The HTML generated by makeinfo is indeed pretty plain, but much can be done with some CSS stylesheets.
4. I want to be able to fiddle the printed layout at a fundamental level
Ok, if you need that, texinfo is not the right choice. But I think the uniformity of texinfo manuals is a good thing, that helps the reader to quickliy find what shes looking for. -- Ole Arndt http://www.sugarshark.com
On 29 October 2011 22:55, Ole Arndt <ole@sugarshark.com> wrote:
to revive an older thread...
2. I want to be able to include pictures and tables, dammit! Texinfo does images and tables. See (Info-goto-node "(texinfo) Images") and (Info-goto-node "(texinfo) Lists and Tables")
Good point. Texinfo to my knowledge can be.. coaxed(?) to do this?
The HTML generated by makeinfo is indeed pretty plain, but much can be done with some CSS stylesheets.
No disagreement there. I personally know enough CSS to be dangerous, but it's a question of whether we should bother with it.
4. I want to be able to fiddle the printed layout at a fundamental level Ok, if you need that, texinfo is not the right choice. But I think the uniformity of texinfo manuals is a good thing, that helps the reader to quickliy find what shes looking for.
Final note: I don't have a strong argument either way. But, some words: 1) I happen to love LaTeX and I'd like to check the current state of LaTeX -> HTML converters before going for Texinfo 2) Mark went through the trouble of actually doing the manual, so for the time being, we'll respect his format choice, over which we have no strong complaints 3) ..and, regarding (2), patches welcome! :) All in all, I believe LaTeX is a fine choice, and not at all broken-enough to require fixing.
participants (4)
-
Blake McBride -
Mark Evenson -
Ole Arndt -
Ville Voutilainen