Re: [help-texinfo] Newbie seeks feedback on a Texinfo learning project

[Eli Zaretskii]

> From: Daniel Birket <address@hidden>
> Date: Thu, 15 Sep 2016 22:40:04 +0000
> 
> 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 "<kdb>", 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 @address@hidden@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").