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

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

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

[Nicolas Goaziou]

Hello,

Alain.Cochard@unistra.fr writes:

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

I have no objection to this, but why is the link to section "Tag
searches" on topic here?

Regards,

-- 
Nicolas Goaziou

Re: 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) | 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     

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

[Nicolas Goaziou]

Hello,

Alain.Cochard@unistra.fr writes:

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

OK.

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

I added the variable in the manual, in a footnote, as you suggested.
However, I made the link point to "Agenda Views" because I think this is
a better starting place for all Agenda related questions.

Thank you.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738