Re: the opposite of the noexport tag

[Loris Bennett]

Ihor Radchenko <yantar92@posteo.net> writes:

> Uwe Brauer <oub@mat.ucm.es> writes:
>
>>> Uwe Brauer <oub@mat.ucm.es> writes:
>>>> I recommend then to clarify this is in the manual: the expression in the 
>>>> manual is 
>>>> `("export")'
>>
>>> What about the attached patch?
>>
>> I added some lines, and run rediff and I hoper therefore the modified patch 
>> is ok.
>>
>>
>> Feel free to use it
>> +  This tag is useful, if the =export= tag is not used on other sections.
>> +  When a tree is tagged
>> +  with =noexport=, Org excludes that tree and its subtrees from
>> +  export.  
>
> I find this part confusing - we first talk about no "export" tags at all
> and then immediately about using with "export" tags. I dropped it in the
> attached patch. Maybe there is a better way to formulate the same?
>
> In the attached patch, I incorporated your other changes, the grammar
> remarks from Loris, and reworded a bit more.
>
> From c82ec6139269cfc5dabf0e2e4d3601143843c782 Mon Sep 17 00:00:00 2001
> Message-ID: 
> <c82ec6139269cfc5dabf0e2e4d3601143843c782.1698137891.git.yantar92@posteo.net>
> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Mon, 23 Oct 2023 15:30:42 +0300
> Subject: [PATCH v2] * doc/org-manual.org: Improve documentation for
>  #+SELECT_TAGS and #+EXCLUDE_TAGS
>
> (Export Settings): Clarify how to define multiple tags per-document.  Reword.
>
> Link: 87y1ftilf3.fsf@mat.ucm.es">https://orgmode.org/list/87y1ftilf3.fsf@mat.ucm.es
> ---
>  doc/org-manual.org | 38 +++++++++++++++++++++++++++-----------
>  1 file changed, 27 insertions(+), 11 deletions(-)
>
> diff --git a/doc/org-manual.org b/doc/org-manual.org
> index c0e9c8d7e..7e4553668 100644
> --- a/doc/org-manual.org
> +++ b/doc/org-manual.org
> @@ -12053,22 +12053,38 @@ ** Export Settings
>  
>    #+cindex: @samp{SELECT_TAGS}, keyword
>    #+vindex: org-export-select-tags
> -  The default value is =("export")=.  When a tree is tagged with
> -  =export= (~org-export-select-tags~), Org selects that tree and its
> -  subtrees for export.  Org excludes trees with =noexport= tags, see
> -  below.  When selectively exporting files with =export= tags set, Org
> -  does not export any text that appears before the first headline.
> +  List of tags that will *only* be selected for export.  The default

I find the emphasised 'only' confusing here, since it implies to me
there the tags might have some other function.  I would find, in analogy
to the corresponding text regarding exclude tags, the following text
better:

  List of tags that will be included in the export.

I assume that 'only' was meant to imply that the list of tags is
exclusive in the sense that no other tags will be exported.  However,
talking about an 'exclusive list' the context of what will be included
in the export is probably not going to be helpful.

Note that the keywords SELECT_TAGS and EXCLUDE_TAGS are not proper
antonyms, which might be a possible source of confusion.  I don't know
how feasible it would be to replace (at least in the sense of an alias),
these terms with, say,

  EXPORT_INCLUDE_TAGS
  EXPORT_EXCLUDE_TAGS

> +  value is ~org-export-select-tags~ =("export")=.  When a tree is
> +  tagged with =export=, Org selects that tree and its subtrees for
> +  export, ignoring all the other sections that do not possess the
> +  =export= tag.
> +
> +  When selectively exporting files with =export= tags set, Org does
> +  not export any text that appears before the first headline.
> +
> +  Note that a file without the =export= or the =noexport= tag will
> +  export all its sections.
> +
> +  To select non-default tags for export, customize
> +  ~org-export-select-tags~ (globally) or add =#+SELECT_TAGS: tag1
> +  tag2= to the document.
>  
>  - =EXCLUDE_TAGS= ::
>  
>    #+cindex: @samp{EXCLUDE_TAGS}, keyword
>    #+vindex: org-export-exclude-tags
> -  The default value is =("noexport")=.  When a tree is tagged with
> -  =noexport= (~org-export-exclude-tags~), Org excludes that tree and
> -  its subtrees from export.  Entries tagged with =noexport= are
> -  unconditionally excluded from the export, even if they have an
> -  =export= tag.  Even if a subtree is not exported, Org executes any
> -  code blocks contained there.
> +  List o tags that will be excluded from export.  The default value is

There is an 'f' missing in

  List o tags

(or an apostrophe in Pirate English).

> +  ~org-export-exclude-tags~ =("noexport")=.  When a tree is tagged
> +  with =noexport=, Org excludes that tree and its subtrees from
> +  export.
> +
> +  Entries tagged with =noexport= are unconditionally excluded from the
> +  export, even if they have an =export= tag.  Even if a subtree is not
> +  exported, Org executes any code blocks contained there.
> +
> +  To select non-default tags for the exclusion, customize
> +  ~org-export-exclude-tags~ (globally) or add =#+EXCLUDE_TAGS: tag1
> +  tag2= to the document.
>  
>  - =TITLE= ::
>  
> -- 
> 2.42.0
-- 
This signature is currently under constuction.