Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Dr. Arne Babenhauserheide]

Richard Stallman <rms@gnu.org> writes:

> So the question is how we can stimulate work to produce the _best_
> result, rather than accepting forever an inferior result.
>
> Any ideas?

I think easy to read documentation of texinfo helps a lot.

I added a section for that to my "programming-essentials" guide; it’s cc
by-sa, so if anyone wants to use that or build on it to help people find
an easier entry into texinfo, feelf free to use it:
https://www.draketo.de/software/programming-basics-wisp#texinfo
Source:
https://hg.sr.ht/~arnebab/draketo/browse/software/programming-basics-wisp.org?rev=5748f320312c#L1943


Since I know that you prefer not to open URLs, here’s the content of the
section (in org-mode syntax):

* Create a manual as package documentation with =texinfo=
:PROPERTIES:
:CUSTOM_ID: texinfo
:END:

Create a =doc/= folder and add a =hello.texi= file.

An *example file* can look like the following:

#+begin_src texinfo :tangle hello/doc/hello.texi
@documentencoding UTF-8
@settitle Hello World
@c This is a comment; The Top node is the first page
@node Top

@c Show the title and clickable Chapter-names as menu
@top
@menu
,* First Steps::
,* API Reference::
@end menu

@contents
@node First Steps
@chapter First Steps
@itemize
@item
Download from ...
@item
Install: @code{make}.
@end itemize

Example:
@lisp
(+ 1 2)
@result{} 3
@end lisp

@node API Reference
@chapter API Reference
@section Procedures
@subsection hello
Print Hello
@example
hello
@end example
#+end_src

Add a =Makefile= in the doc/ folder:

#+begin_src makefile :tangle hello/doc/Makefile
all: hello.info hello.epub hello_html/index.html
hello.info: hello.texi
        makeinfo hello.texi
hello.epub: hello.texi
        makeinfo --epub hello.texi
hello_html/index.html: hello.texi
        makeinfo --html hello.texi
#+end_src

Run make:

#+begin_src bash
make
#+end_src

Read the docs with =calibre= or the =browser= or plain =info=:

#+begin_src bash
calibre hello.epub & \
firefox hello_html/index.html & \
info -f ./hello.info
#+end_src

/The HTML output is plain. You can adapt it with CSS by adding
=--css-include=FILENAME= or =--css-ref=URL=./

/Alternately you can write an [[https://orgmode.org][Org Mode]] document and 
evaluate
=(require 'ox-texinfo)= to activate exporting to texinfo./

# For regular Guile programs, add guild doc-snarf.


Best wishes,
Arne

signature.asc
Description: PGP signature