emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH] Improve documentation of #+startup keyword
@ 2021-03-19 12:03 Timothy
  2021-04-26  7:45 ` Bastien
  0 siblings, 1 reply; 4+ messages in thread
From: Timothy @ 2021-03-19 12:03 UTC (permalink / raw)
  To: org-mode-email

[-- Attachment #1: Type: text/plain, Size: 478 bytes --]

Hello all,

I was talking to someone who was finding the behaviour of `#+startup'
confusing, and they managed to work out a table summarising the
behaviour.

I think that this would be a good addition to the manual, and help
clarify the behaviour --- so I've prepared a little patch to the manual.
I notice that there are some `#+cindex' lines lying around but I'm not
quite sure what they do. Please let me know if I should add anything
like that etc.

All the best,
*Timothy*

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-clarify-startup-behaviour.patch --]
[-- Type: text/x-patch, Size: 1720 bytes --]

From 8ff32dfbf2e14419eb542d58ee39c1545f34354b Mon Sep 17 00:00:00 2001
From: TEC <tec@tecosaur.com>
Date: Fri, 19 Mar 2021 20:01:03 +0800
Subject: [PATCH] doc/org-manual.org: clarify #+startup behaviour

* doc/org-manual.org: clarify the behaviour that each #+startup option
implies.
---
 doc/org-manual.org | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index e8763ff17..a005cce52 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -598,6 +598,19 @@ *** Initial visibility
   is requested by startup options and =VISIBILITY= properties in
   individual entries.
 
+A summary of each keyword's behaviour may be seen in the table below.
+| #+startup:          | org-startup-folded | VISIBILITY | shows headings | shows body |
+|---------------------+--------------------+------------+----------------+------------|
+| overview (or fold)  | t                  | x          | lvl1           |            |
+| content             | 'content           | x          | all            |            |
+| show2levels         | 'show2levels       | x          | lvl1-2         |            |
+| ...                 | 'showNlevels       | x          | lvl1-N         |            |
+| show5levels         | 'show5levels       | x          | lvl1-5         |            |
+| showall (or nofold) | nil                | x          | all            | x          |
+| showeverything      | 'showeverything    |            | all            | x          |
+| <DEFAULT>           | 'showeverything    |            | all            | x          |
+
+
 *** Catching invisible edits
 :PROPERTIES:
 :DESCRIPTION: Preventing mistakes when editing invisible parts.
-- 
2.30.1


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] Improve documentation of #+startup keyword
  2021-03-19 12:03 [PATCH] Improve documentation of #+startup keyword Timothy
@ 2021-04-26  7:45 ` Bastien
  2021-04-26  8:04   ` Detlef Steuer
  0 siblings, 1 reply; 4+ messages in thread
From: Bastien @ 2021-04-26  7:45 UTC (permalink / raw)
  To: Timothy; +Cc: org-mode-email

Hi Timothy,

Timothy <tecosaur@gmail.com> writes:

> I was talking to someone who was finding the behaviour of `#+startup'
> confusing, and they managed to work out a table summarising the
> behaviour.
>
> I think that this would be a good addition to the manual, and help
> clarify the behaviour --- so I've prepared a little patch to the manual.

Thanks for the patch.  I think it better belongs to a worg page, as we
try to avoid overloading the quite-already-big manual.  Can you make
this a contribution to Worg?

> I notice that there are some `#+cindex' lines lying around but I'm not
> quite sure what they do. Please let me know if I should add anything
> like that etc.

#+cindex keywords add an entry in the concept index of other versions
of the manual (HTML, PDF, Info, etc.)


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] Improve documentation of #+startup keyword
  2021-04-26  7:45 ` Bastien
@ 2021-04-26  8:04   ` Detlef Steuer
  2021-04-26  8:21     ` Bastien
  0 siblings, 1 reply; 4+ messages in thread
From: Detlef Steuer @ 2021-04-26  8:04 UTC (permalink / raw)
  To: emacs-orgmode

Am Mon, 26 Apr 2021 09:45:36 +0200
schrieb Bastien <bzg@gnu.org>:

> > I think that this would be a good addition to the manual, and help
> > clarify the behaviour --- so I've prepared a little patch to the
> > manual.  
> 
> Thanks for the patch.  I think it better belongs to a worg page, as we
> try to avoid overloading the quite-already-big manual.  Can you make
> this a contribution to Worg?

I really would like to have as much as possible in the manual.

My guess is, nobody prints it anymore, so the old concers about thick
manuals are irrelevant today.

If I must start looking through worg to find some information, my chance
of finding it has already halfed. :-)

Just my 2c
Detlef


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] Improve documentation of #+startup keyword
  2021-04-26  8:04   ` Detlef Steuer
@ 2021-04-26  8:21     ` Bastien
  0 siblings, 0 replies; 4+ messages in thread
From: Bastien @ 2021-04-26  8:21 UTC (permalink / raw)
  To: Detlef Steuer; +Cc: emacs-orgmode

Hi Detlef,

Detlef Steuer <steuer@hsu-hh.de> writes:

> I really would like to have as much as possible in the manual.

Explanations are always good in the reference manual, yes, but
clarifications belong in the community-driven extended manual that
is Worg, IMO.  I think this change would overload the manual without
addding much to it.


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2021-04-26  8:22 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-19 12:03 [PATCH] Improve documentation of #+startup keyword Timothy
2021-04-26  7:45 ` Bastien
2021-04-26  8:04   ` Detlef Steuer
2021-04-26  8:21     ` Bastien

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).