> From: Daniel Birket
> Date: Thu, 15 Sep 2016 22:40:04 +
>
> If you are inclined to offer someone new to Texinfo your advice, please skim
> the texi file at the link below. I’m
> interested in your feedback _on my use of Texinfo markup_ as I’m new to the
> medium. My purpose is to learn
> enough to help with GNU documentation as I expect that I’m too out of date to
> help code.
>
> https://github.com/daniel-birket/markdown-mode-texinfo
It's quite good, actually. Good job!
Some comments, which I hope will be helpful:
. Don't use capitalized entries in @cindex, because sorting of index
entries might give different results in different locales. Having
some index entries capitalized and others not is definitely not a
good idea. The convention is to have all @cindex entries start
with a lower-case letter.
. Avoid having more than one index entry with the same wording: this
creates index entries like "FOO <1>", "FOO <2>", etc. which are not
useful. Either leave only one entry (and have a cross-references
in all other places to the one place which describes the
issue/subject), or qualify each entry with some context, so that
they will no longer be worded identically.
. Also try to avoid closely located index entries that begin the
same, like this:
@cindex How to Download a RedHat Package
@cindex How to Download a Fedora Package
Instead, either make a single index entry, or remove the "How to
Download" from the entries.
Specifically for that section, I'd not create a separate index
entry for each OS flavor, because it's unlikely the reader will
look up their OS name. Just "How to Download" should be enough.
. Try not to start a sentence like this:
@command{emacs} is a powerful editor ...
The resulting sentence in the manual will begin with a lower-case
letter, which is not correct English. Slight rewording is all you
need:
The @command{emacs} editor is a powerful package ...
. You seem to always put Lisp examples inside @cartouche. Not sure
it's a good idea (for starters, it leaves you less space on a
line); it's certainly not the GNU documentation practice.
. @dots{} (or @enddots{}, as the case may be) will produce a nicer
output than literal 3 periods.
. A table that lists key bindings, such as this one:
@table @kbd
@item C-c C-a
...
@item C-c C-c
should have a @kindex entry for each key it describes.
. Tags, such as "", should be in @code or @samp, but not as
plain text.
. Text such as this:
This inserts a reference link of the form @samp{[text][label]}
should use @var for the meta-syntactic variables, like this:
This inserts a reference link of the form @samp{[@var{text}][@var{label}]}
The stuff inside @var should be lowercase, because the Info format
upcases it.
. Acronyms, such as URL and URI, are better given the @acronym
markup. Or maybe you will like @sc better.
. Quoted text should use ``..'', not "..", because the former
produces a nicer output. However, if you use quoting to introduce
terminology, use @dfn instead.
. Some markup was left at its markdown style (example:
`markdown-header-scaling`). Also, some instances of "nil" don't
have the @code markup. Some keys don't have the @key markup
(examples: "mouse-1", "RET").
