Poor coverage of (concept) index in documentation

[stefanrueger]

Now that the functionality and documentation of AVRDUDE has grown over the last couple of years, I couldn't help noticing that the (concept) index of the documentation does not have a great coverage:

It is a matter of carefully sprinkling a number of relevant @cindex entries into src/doc/avrdude.texi. That needs attention to detail and style, but would be an activity worth pursuing before the next release.

[Ho-Ro]

The 1st step can be done automatically:

#!/usr/bin/python

'''
Create @cindex entries for all @section, @subsection and @subsubsection entries.
Also create "@cindex Option -..." entries for all "@item -..." entries.
And finally replace the ugly "-x ..." index entries with "Option -x ...".
Write new texi file to stdout.
'''

filename = 'avrdude.texi'

with open( filename, 'r' ) as texi:
  for line in texi:
    cindex = None
    for tag, index_tag in (
        ( '@section', '@cindex' ),
        ( '@subsection', '@cindex' ),
        ( '@subsubsection', '@cindex' ),
        ( '@chapter', '@cindex' ),
        ( '@item -', '@cindex Option -' )
    ):
      # create index from structure elements
      if line.startswith( tag ):
        cindex = line.replace( tag, index_tag  )
        break
    # reformat Index "-x ..." -> "Option -x"
    if line.startswith( '@cindex @code{-x}' ):
      line = line.replace( '@cindex @code{-x}', '@cindex Option -x' )

    print( line, end='' )

    if cindex:
      print( cindex, end='' )

EDIT: add line ( '@chapter', '@cindex' ),

Next steps should be an aligned wording, e.g. Configuration File vs. Configuration Files, renaming Configuration Files in the Windows section to Windows Configuration Files, unifying upper/lower case in the headers and removing section A.2.4 b/c this is n/a for Windows.

[Ho-Ro]

Another small change populates the index even more with all programmer types, but maybe this is too much:

diff --git a/src/doc/programmers.cmake b/src/doc/programmers.cmake
index b8611c0..76c77ac 100644
--- a/src/doc/programmers.cmake
+++ b/src/doc/programmers.cmake
@@ -20,7 +20,9 @@ file(STRINGS ${TXT_FILE} TXT_CONTENTS REGEX "=")
 
 SET(TEXI_CONTENTS "")
 foreach(TXT_LINE IN LISTS TXT_CONTENTS)
-    string(REGEX REPLACE "^[ \t]*([^ \t]+)[ \t]*=[ \t]*(.*)$" "@item @code{\\1} @tab \\2" TEXI_LINE "${TXT_LINE}")
+    string(REGEX REPLACE "^[ \t]*([^ \t]+)[ \t]*=[ \t]*(.*)$"
+           "@item @code{\\1} @tab \\2\n@cindex @code{\\1}"
+           TEXI_LINE "${TXT_LINE}")
     string(REGEX REPLACE "[ \t>]*,?[ \t>]*<?(http[s]?://[^ \t>]+)>?" ",@*\n@url{\\1}" TEXI_LINE "${TEXI_LINE}")
     set(TEXI_CONTENTS "${TEXI_CONTENTS}${TEXI_LINE}\n")
 endforeach()

[stefanrueger]

@Ho-Ro Great ideas! Please take the lead for applying these! Looking forward to a PR

[mcuee]

#1592 has been merged.

@stefanrueger
Do you want to keep this open or you want to close this issue for now?

[stefanrueger]

I'd like to keep this open. The automated additions of PR #1592 are a great but the index deserves better