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

[Alain . Cochard]

Nicolas Goaziou writes on Wed 16 May 2018 22:12:

 > > 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.

 > [...] why is the link to section "Tag searches" on topic here?

My reasoning was that, at section "6.2" and upon sequential reading,
the user does not really know what agenda files are yet.  I was hoping
that the excerpt:

  ‘C-c a m     (org-tags-view)’
       Create a global list of tag matches from all agenda files.
           *Note Matching tags and properties::.

could him to get acquainted with the concept.  In fact I hesitated
between this link and, as is sometimes done in similar cases, the link
to "10 Agenda views"[fn:1], but which I found too general.

But perhaps it is not pertinent to assume sequential reading.  Or
perhaps (a digest of) "10 Agenda views" should appear earlier in the
manual.

Regards,
alain

[fn:1] e.g., in "5.1 Basic TODO functionality":

‘C-c a t     (org-todo-list)’
     Show the global TODO list.  Collects the TODO items (with not-DONE
     states) from all agenda files (*note Agenda views::) into a single
     buffer.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
IPG (Institut de Physique du Globe) | address@hidden
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