Should org-complete-tags-always-offer-all-agenda-tags be documented in the manual? [was: Tag completion does not work well with ...]

[Alain.Cochard@unistra.fr]

Nicolas Goaziou writes on Fri  4 May 2018 23:44:

 > > Incidentally, shouldn't this variable be documented in the
 > > manual?  (Section "6.2 Setting tags" would seem a natural place
 > > for that.)  I had to resort to internet search...

 > I don't know specifically about this one, but not all variables can
 > be documented in the manual, there are too many of them.

Yes, I understand that. 

 > An alternate way to find about a variable is to explore Org
 > variables with
 > 
 >   M-x customize-group <RET> org

Thanks for the reminder.  In my case, it would have been useful.

In general, though, I still feel it would make sense to document it,
especially considering that other ways than the default are already
documented.  Consider this excerpt from section "6.2 Setting tags":

      Org supports tag insertion based on a _list of tags_.  By
   default this list is constructed dynamically, containing all tags
   currently used in the buffer.  You may also globally specify a hard
   list of tags with the variable ‘org-tag-alist’.  Finally you can
   set the default tags for a given file [...]

One could have a footnote after "currently used in the buffer" which
could be something like:

   One can have this list contain all tags used in all agenda files
   (see [[link to section "6.4 Tag searches"]]) by customizing
   variable org-complete-tags-always-offer-all-agenda-tags.

Regards

-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106] | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France    | Fax:   +33 (0)3 68 85 01 25