[Worg] CSS improvements

[Worg] CSS improvements

[Adam Porter]

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

Hi Bastien, et al,

Please see the attached patch which makes some minor improvements to 
Worg's CSS.  I thought I should get your approval before pushing it.

Thanks,
Adam

[-- Attachment #2: 0001-style-worg.css-Minor-improvements.patch --]
[-- Type: text/x-patch, Size: 1642 bytes --]

From ab068940b5e63189dae3eddae84aaa2b03d6b6ef Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sat, 23 Mar 2024 09:31:18 -0500
Subject: [PATCH] * style/worg.css: Minor improvements

(@media all body .title): Specify font size in ems.

(@media all h1): Slightly reduce bottom margin so as not to leave a
large space between the title and subtitle.

(@media all .subtitle): Actually style this (apparently few pages use
subtitles yet).

(@media all .org-center): Actually style this so that "#+begin_center"
blocks are centered and fit with the rest of the theme, allowing these
blocks to be used to make certain text stand out.
---
 style/worg.css | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/style/worg.css b/style/worg.css
index 30cadb1b..a675ac5b 100644
--- a/style/worg.css
+++ b/style/worg.css
@@ -61,7 +61,7 @@
     
     body .title {
 	margin-left: 0px;
-	font-size: 22pt;
+	font-size: 2.5em;
     }
 
     #org-div-home-and-up{
@@ -120,7 +120,7 @@
     }
 
     h1 {
-	margin-bottom: 1.5em;
+	margin-bottom: 1em;
 	margin-right: 7%;
     }
 
@@ -315,6 +315,10 @@
 	/* font-lock-string-face */
 	color: #ccc79a;
     }
+    .subtitle {
+	font-size: 1.5em;
+	font-style: italic;
+    }
     .todo-comment {
 	/* todo-comment-face */
 	color: #ffffff;
@@ -422,6 +426,14 @@
 	/* calendar-today */
 	text-decoration: underline;
     }
+    .org-center {
+	text-align: center;
+	margin-top: 1em;
+	margin-bottom: 1em;
+	background: #587e7226;
+	padding-top: 0.2em;
+	padding-bottom: 0.2em;
+    }
     .org-comment {
 	/* font-lock-comment-face */
 	color: #b22222;
-- 
2.30.2

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

> (@media all .org-center): Actually style this so that "#+begin_center"
> blocks are centered and fit with the rest of the theme, allowing these
> blocks to be used to make certain text stand out.

I am not sure if centered text should stand out.
AFAIU, you want to add this style for the sole purpose of highlighting

#+begin_center
"Should I use one big Org file or many small ones?"
#+end_center

FYI, we usually do

: "Should I use one big Org file or many small ones?"

to make text stand out.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [Worg] CSS improvements

[Adam Porter]

On 3/23/24 09:49, Ihor Radchenko wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> (@media all .org-center): Actually style this so that "#+begin_center"
>> blocks are centered and fit with the rest of the theme, allowing these
>> blocks to be used to make certain text stand out.
> 
> I am not sure if centered text should stand out.
> AFAIU, you want to add this style for the sole purpose of highlighting

What is the purpose of centering text if not to make it stand out?

> FYI, we usually do
> 
> : "Should I use one big Org file or many small ones?"
> 
> to make text stand out.

Yes, but that makes it source code, which makes it monospaced, which is 
not appropriate except for source code.

Besides, the .org-center class is not even styled right now, so it isn't 
even given a unique appearance on Worg right now.  So why not use it 
this way?

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>> I am not sure if centered text should stand out.
>> AFAIU, you want to add this style for the sole purpose of highlighting
>
> What is the purpose of centering text if not to make it stand out?

To align text. I am not sure why anything more is necessary - it
is certainly counter-intuitive for me that "center" means something more
than just alignment.

If you need extra highlighting, we may introduce a dedicated style and
apply it via special block.

>> FYI, we usually do
>> 
>> : "Should I use one big Org file or many small ones?"
>> 
>> to make text stand out.
>
> Yes, but that makes it source code, which makes it monospaced, which is 
> not appropriate except for source code.

Agree.
Having some kind of style equivalent to beamer "alert" will be useful.

> Besides, the .org-center class is not even styled right now, so it isn't 
> even given a unique appearance on Worg right now.  So why not use it 
> this way?

Mostly because it is unexpected, as I described above.
I'd prefer to stick closer to the semantics and just apply alignment to
center blocks.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [Worg] CSS improvements

[Dr. Arne Babenhauserheide]

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


Ihor Radchenko <yantar92@posteo.net> writes:

> Adam Porter <adam@alphapapa.net> writes:
>
>>> I am not sure if centered text should stand out.
>>> AFAIU, you want to add this style for the sole purpose of highlighting
>>
>> What is the purpose of centering text if not to make it stand out?
>
> To align text. I am not sure why anything more is necessary - it
> is certainly counter-intuitive for me that "center" means something more
> than just alignment.
>
> If you need extra highlighting, we may introduce a dedicated style and
> apply it via special block.

I defined a "kasten" block for my own page, maybe you can re-use that:

# ELISP
(add-to-list 'org-structure-template-alist '("k" "#+begin_kasten\n?\n#+end_kasten" "<div class=\"kasten\">?</div>"))

# ORG-MODE
# kasten-Environment for full-width boxed text.
#+latex_header: \definecolor{cream}{rgb}{1.0, 0.99, 0.82}
#+latex_header: \provideenvironment{kasten}% level0
#+latex_header:     {\begin{tcolorbox}[colback=cream, sharp corners]%
#+latex_header:         \medskip%
#+latex_header:     }
#+latex_header:     {\medskip\end{tcolorbox}%
#+latex_header:     }

# CSS:
/* full-width boxed text */
.kasten {
    color: #111;
    text-align: justify;
    clear: both;
    border-top: 1px solid gray !important;
    border-right: 0px none gray !important;
    border-left: 0px none gray !important;
    border-bottom: 1px solid gray !important;
    background-color: #f6efca;
    border-top: thin solid gray;
    border-bottom: thin solid gray;
    float: left;
    width: 100%;
    z-index: 1;
    margin-top:20px;
    margin-bottom:20px;
}

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: [Worg] CSS improvements

[Adam Porter]

On 3/24/24 03:56, Ihor Radchenko wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>>> I am not sure if centered text should stand out.
>>> AFAIU, you want to add this style for the sole purpose of highlighting
>>
>> What is the purpose of centering text if not to make it stand out?
> 
> To align text. I am not sure why anything more is necessary - it
> is certainly counter-intuitive for me that "center" means something more
> than just alignment.

Again, what is the purpose of centering text?  The answer, "To align 
text," is tautological.

Especially, on Worg, where the whole site serves as a kind of extended 
user manual, the purpose of centering text is, what, if not to make it 
stand out?

> If you need extra highlighting, we may introduce a dedicated style and
> apply it via special block.

Why, when we already have #+begin_center?  Currently it's not even used 
at all.  This would not change anything that already exists; it would 
make something that already exists useful.

> Mostly because it is unexpected, as I described above.
> I'd prefer to stick closer to the semantics and just apply alignment to
> center blocks.

*shrug*  Worg has existed for years without even doing anything with 
#+begin_center blocks--not even centering them.  I propose that we make 
it useful and serve its natural purpose, rather than adding a special 
new block that most users won't even know about (having to find it in 
the voluminous Worg content isn't likely to happen for most users).

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>>> What is the purpose of centering text if not to make it stand out?
>> 
>> To align text. I am not sure why anything more is necessary - it
>> is certainly counter-intuitive for me that "center" means something more
>> than just alignment.
>
> Again, what is the purpose of centering text?  The answer, "To align 
> text," is tautological.

I am very confused. Of course, it is tautological. "center" container is
aiming to align the text. That's why it is named "center".

> Especially, on Worg, where the whole site serves as a kind of extended 
> user manual, the purpose of centering text is, what, if not to make it 
> stand out?

To align text... I really do not understand why one would _anticipate_
that #+begin_center is doing anything other than center alignment.

>> If you need extra highlighting, we may introduce a dedicated style and
>> apply it via special block.
>
> Why, when we already have #+begin_center?  Currently it's not even used 
> at all.  This would not change anything that already exists; it would 
> make something that already exists useful.

It would break expectations.
It will also differ from ox-html output with the default css style
`org-html-style-default':

  .org-center { margin-left: auto; margin-right: auto; text-align: center; }

>> Mostly because it is unexpected, as I described above.
>> I'd prefer to stick closer to the semantics and just apply alignment to
>> center blocks.
>
> *shrug*  Worg has existed for years without even doing anything with 
> #+begin_center blocks--not even centering them.  I propose that we make 
> it useful and serve its natural purpose, rather than adding a special 
> new block that most users won't even know about (having to find it in 
> the voluminous Worg content isn't likely to happen for most users).

I do not see how, without documentation, one would expect that
#+begin_center can be used for highlighting and not for text alignment.
From my point of view, it is worse than a special block - not only this
ad-hoc convention is not documented; it will also break expectations
about what #+begin_center does.

What about:

1. Introducing a new special block for highlighting
2. Documenting it in https://orgmode.org/worg/worg-editing.html

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [Worg] CSS improvements

[David Rogers]

Adam Porter <adam@alphapapa.net> writes:

> On 3/24/24 03:56, Ihor Radchenko wrote: 
>> Adam Porter <adam@alphapapa.net> writes:  
>>>> I am not sure if centered text should stand out.  AFAIU, you 
>>>> want to add this style for the sole purpose of highlighting 
>>> 
>>> What is the purpose of centering text if not to make it stand 
>>> out? 
>> To align text. I am not sure why anything more is necessary - 
>> it is certainly counter-intuitive for me that "center" means 
>> something more than just alignment. 
> 
> Again, what is the purpose of centering text?  The answer, "To 
> align text," is tautological. 

I don't agree that it's tautological. Aligning text differently is 
already a method of emphasizing it. Double- or multi-emphasizing 
that text by adding even more styles to it leads me to question 
the value of centering it in the first place. I'm not claiming 
it's somehow wrong to use more than one emphasis though - this is 
just a thought!!!!

:)

-- 
David Rogers

Re: [Worg] CSS improvements

[Adam Porter]

On 3/26/24 09:48, Ihor Radchenko wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>>>> What is the purpose of centering text if not to make it stand out?
>>>
>>> To align text. I am not sure why anything more is necessary - it
>>> is certainly counter-intuitive for me that "center" means something more
>>> than just alignment.
>>
>> Again, what is the purpose of centering text?  The answer, "To align
>> text," is tautological.
> 
> I am very confused. Of course, it is tautological. "center" container is
> aiming to align the text. That's why it is named "center".

Yes, but why do we center text?  That's what I'm asking.

>> Especially, on Worg, where the whole site serves as a kind of extended
>> user manual, the purpose of centering text is, what, if not to make it
>> stand out?
> 
> To align text... I really do not understand why one would _anticipate_
> that #+begin_center is doing anything other than center alignment.

Of course, I'm not suggesting that this be the default for Org's HTML 
export CSS.  I'm suggesting that, on Worg, since the .org-center class 
hasn't even been styled, we might as well use it for this purpose--to 
make text stand out--since that's generally the purpose of centering 
text anyway.

>>> If you need extra highlighting, we may introduce a dedicated style and
>>> apply it via special block.
>>
>> Why, when we already have #+begin_center?  Currently it's not even used
>> at all.  This would not change anything that already exists; it would
>> make something that already exists useful.
> 
> It would break expectations.
> It will also differ from ox-html output with the default css style
> `org-html-style-default':

Worg already differs significantly from the ox-html default styles, so 
why not in this way also?

>>> Mostly because it is unexpected, as I described above.
>>> I'd prefer to stick closer to the semantics and just apply alignment to
>>> center blocks.
>>
>> *shrug*  Worg has existed for years without even doing anything with
>> #+begin_center blocks--not even centering them.  I propose that we make
>> it useful and serve its natural purpose, rather than adding a special
>> new block that most users won't even know about (having to find it in
>> the voluminous Worg content isn't likely to happen for most users).
> 
> I do not see how, without documentation, one would expect that
> #+begin_center can be used for highlighting and not for text alignment.
>  From my point of view, it is worse than a special block - not only this
> ad-hoc convention is not documented; it will also break expectations
> about what #+begin_center does.

Again, this is just for Worg, and centering hasn't even had any effect 
for years.  There seem to be no expectations to break.

> What about:
> 
> 1. Introducing a new special block for highlighting
> 2. Documenting it in https://orgmode.org/worg/worg-editing.html

I think that such a new special block would likely go unused in favor of 
default blocks.  The cognitive load of learning how to contribute to 
Worg is already pretty high.  We see this same pattern in contributions 
to Emacs and Org themselves: code is often unidiomatic because it takes 
a long time to learn all the idioms, and it's often not obvious what the 
idiomatic way to do something is.  The same is true for contributions to 
documentation.  Worg is no different.

So I would still suggest that, on Worg, we use my suggested styling on 
#+begin_center blocks.  This would make them useful and fulfill their 
natural purpose.

I understand your general objection--and I wouldn't suggest it for Org's 
default export CSS--but I think that, for Worg specifically, it needn't 
apply.

Since Worg is updated with relatively low frequency, anyway, perhaps 
this suggestion could be tried as an experiment.  If problems are found 
with it, then the extra styling, beyond merely centering the text, could 
be reverted.  Nothing is permanent here; we've probably spilled more 
virtual ink on this topic than would be affected by the change.

Anyway, if this idea is vetoed, it would still be good to have some way 
to make text stand out in a standard way, similar to various HTML 
documentation styles in other projects (to avoid resorting to inline 
HTML).  It seems like a missing feature on Worg.

And the other changes in the patch would be good to have, regardless.

Thanks,
Adam

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

> ...
> So I would still suggest that, on Worg, we use my suggested styling on 
> #+begin_center blocks.  This would make them useful and fulfill their 
> natural purpose.

I think that we have a principal disagreement here. For me, highlighting
#+begin_center blocks is extremely unnatural. I would never expect that,
and I would be extremely surprised by that.

I guess we can make this into a poll... (I have no better ideas on how
to resolve the disagreement)

> Since Worg is updated with relatively low frequency, anyway, perhaps 
> this suggestion could be tried as an experiment.  If problems are found 
> with it, then the extra styling, beyond merely centering the text, could 
> be reverted.  Nothing is permanent here; we've probably spilled more 
> virtual ink on this topic than would be affected by the change.

I am mostly worried about future effect.
We will not have any problems with it in the near future, because the
only user of this style will be your new WORG page.

> Anyway, if this idea is vetoed, it would still be good to have some way 
> to make text stand out in a standard way, similar to various HTML 
> documentation styles in other projects (to avoid resorting to inline 
> HTML).  It seems like a missing feature on Worg.

Agree.

> And the other changes in the patch would be good to have, regardless.

Yup.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [Worg] CSS improvements

[Adam Porter]

On 3/28/24 06:44, Ihor Radchenko wrote:

>> So I would still suggest that, on Worg, we use my suggested styling
>> on #+begin_center blocks.  This would make them useful and fulfill
>> their natural purpose.
> 
> I think that we have a principal disagreement here. For me,
> highlighting #+begin_center blocks is extremely unnatural. I would
> never expect that, and I would be extremely surprised by that.

It's a mild background color fitting with the theme of the Worg site.

And as I've said, centering has not even had any effect up til now.  So
I don't think it's a big deal.

>> Since Worg is updated with relatively low frequency, anyway,
>> perhaps this suggestion could be tried as an experiment.  If
>> problems are found with it, then the extra styling, beyond merely
>> centering the text, could be reverted.  Nothing is permanent here;
>> we've probably spilled more virtual ink on this topic than would be
>> affected by the change.
> 
> I am mostly worried about future effect. We will not have any
> problems with it in the near future, because the only user of this
> style will be your new WORG page.

I don't know what there is to worry about.  If someone centers some text 
on a Worg page to make it stand out, it would...stand out?  :)

>> Anyway, if this idea is vetoed, it would still be good to have some
>> way to make text stand out in a standard way, similar to various
>> HTML documentation styles in other projects (to avoid resorting to
>> inline HTML).  It seems like a missing feature on Worg.
> 
> Agree.
> 
>> And the other changes in the patch would be good to have,
>> regardless.
> 
> Yup.

> I guess we can make this into a poll... (I have no better ideas on
> how to resolve the disagreement)

I think that's unnecessary.  Worg isn't a democracy, after all.  If you
are vetoing the idea, then let it be vetoed, and let us move on with the 
rest of the proposed changes.  I'll go ahead and push them, without the 
background color.

Thanks,
Adam

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>> I guess we can make this into a poll... (I have no better ideas on
>> how to resolve the disagreement)
>
> I think that's unnecessary.  Worg isn't a democracy, after all.  If you
> are vetoing the idea, then let it be vetoed, and let us move on with the 
> rest of the proposed changes.  I'll go ahead and push them, without the 
> background color.

It is not about democracy or veto. We disagree about expectations for
#+begin_center. Expectations are not about me or you, but rather about
what WORG authors will expect. So, asking people makes sense.

Also, we may consider re-using inlinetask style for TODO: entries.

Rather than
#+begin_center
TODO: Even better, find a volunteer to maintain this information!
#+end_center

We can do

**************************** TODO Even better, ...

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [Worg] CSS improvements

[Adam Porter]

On 3/28/24 08:18, Ihor Radchenko wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>>> I guess we can make this into a poll... (I have no better ideas on
>>> how to resolve the disagreement)
>>
>> I think that's unnecessary.  Worg isn't a democracy, after all.  If you
>> are vetoing the idea, then let it be vetoed, and let us move on with the
>> rest of the proposed changes.  I'll go ahead and push them, without the
>> background color.
> 
> It is not about democracy or veto. We disagree about expectations for
> #+begin_center. Expectations are not about me or you, but rather about
> what WORG authors will expect. So, asking people makes sense.

If you feel strongly enough about the background color idea (which would 
be an interesting reversal ;), I'll leave that in your hands. 
Otherwise, I don't feel strongly enough about it to pursue a poll.

> Also, we may consider re-using inlinetask style for TODO: entries.
> 
> Rather than
> #+begin_center
> TODO: Even better, find a volunteer to maintain this information!
> #+end_center
> 
> We can do
> 
> **************************** TODO Even better, ...

That is a lot of asterisks, and I can't remember if inline tasks are 
enabled by default.  :)  But in general, sure, I've no objection.  I 
think that we should have some standard way to encode tasks within Worg 
documents, regardless of what it is.

Thanks,
Adam

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>> It is not about democracy or veto. We disagree about expectations for
>> #+begin_center. Expectations are not about me or you, but rather about
>> what WORG authors will expect. So, asking people makes sense.
>
> If you feel strongly enough about the background color idea (which would 
> be an interesting reversal ;), I'll leave that in your hands. 
> Otherwise, I don't feel strongly enough about it to pursue a poll.

No poll then :) I was worried that you feel strongly about this.

>> Also, we may consider re-using inlinetask style for TODO: entries.
>> 
>> Rather than
>> #+begin_center
>> TODO: Even better, find a volunteer to maintain this information!
>> #+end_center
>> 
>> We can do
>> 
>> **************************** TODO Even better, ...
>
> That is a lot of asterisks, and I can't remember if inline tasks are 
> enabled by default.  :)  But in general, sure, I've no objection.  I 
> think that we should have some standard way to encode tasks within Worg 
> documents, regardless of what it is.

Yeah. And... we do.
https://orgmode.org/worg/worg-editing.html#orgce51883

Just a normal heading with TODO keyword.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

How to organize tasks about Worg within Worg documents (was: Re: [Worg] CSS improvements)

[Adam Porter]

On 3/29/24 04:48, Ihor Radchenko wrote:

>>> Also, we may consider re-using inlinetask style for TODO: entries.
>>>
>>> Rather than
>>> #+begin_center
>>> TODO: Even better, find a volunteer to maintain this information!
>>> #+end_center
>>>
>>> We can do
>>>
>>> **************************** TODO Even better, ...
>>
>> That is a lot of asterisks, and I can't remember if inline tasks are
>> enabled by default.  :)  But in general, sure, I've no objection.  I
>> think that we should have some standard way to encode tasks within Worg
>> documents, regardless of what it is.
> 
> Yeah. And... we do.
> https://orgmode.org/worg/worg-editing.html#orgce51883
> 
> Just a normal heading with TODO keyword.

I'm not sure that page really covers the question of how to present 
tasks about the document within the same document.

Using a normal heading for a task would "commandeer" the structure of 
the document, which I think is a real problem.

ISTM that there are a few potential solutions:

a. Using inline tasks.  Although not enabled by default, they seem to
    solve the problem pretty well.

b. Using commented lines, i.e.

      # TODO: Improve this information.

    Potentially we could even comment Org syntax within the file, like:

      # * TODO Improve this information  :research_needed:

    Which encodes a normal Org heading but as a commented line, so it 	
    wouldn't affect the structure of the document itself.  Of course,
    that would not appear in the exported content, which is probably not
    what we want; but those headings could still be collected, e.g. by
    something like magit-todos.

c. Keeping tasks in a separate file.  We do already have the /todo.org
    file, so maybe this is what we should standardize on, i.e. never
    putting tasks in the documents themselves but only in this file.

Regardless of the decision, I do think that having this stated as a 
policy somewhere would be helpful.

WDYT?

Re: How to organize tasks about Worg within Worg documents (was: Re: [Worg] CSS improvements)

[Thomas S. Dye]

Aloha all,

Adam Porter <adam@alphapapa.net> writes:

> On 3/29/24 04:48, Ihor Radchenko wrote:
>
>>>> Also, we may consider re-using inlinetask style for TODO: 
>>>> entries.
>>>>
>>>> Rather than
>>>> #+begin_center
>>>> TODO: Even better, find a volunteer to maintain this 
>>>> information!
>>>> #+end_center
>>>>
>>>> We can do
>>>>
>>>> **************************** TODO Even better, ...
>>>
>>> That is a lot of asterisks, and I can't remember if inline 
>>> tasks are
>>> enabled by default.  :)  But in general, sure, I've no 
>>> objection.  I
>>> think that we should have some standard way to encode tasks 
>>> within Worg
>>> documents, regardless of what it is.
>> Yeah. And... we do.
>> https://orgmode.org/worg/worg-editing.html#orgce51883
>> Just a normal heading with TODO keyword.
>
> I'm not sure that page really covers the question of how to 
> present tasks about
> the document within the same document.
>
> Using a normal heading for a task would "commandeer" the 
> structure of the
> document, which I think is a real problem.
>
> ISTM that there are a few potential solutions:
>
> a. Using inline tasks.  Although not enabled by default, they 
> seem to
>    solve the problem pretty well.
>
> b. Using commented lines, i.e.
>
>      # TODO: Improve this information.
>
>    Potentially we could even comment Org syntax within the file, 
>    like:
>
>      # * TODO Improve this information  :research_needed:
>
>    Which encodes a normal Org heading but as a commented line, 
>    so it 	
>    wouldn't affect the structure of the document itself.  Of 
>    course,
>    that would not appear in the exported content, which is 
>    probably not
>    what we want; but those headings could still be collected, 
>    e.g. by
>    something like magit-todos.
>
> c. Keeping tasks in a separate file.  We do already have the 
> /todo.org
>    file, so maybe this is what we should standardize on, i.e. 
>    never
>    putting tasks in the documents themselves but only in this 
>    file.

Here's another potential solution that I find useful.

d. Keeping tasks under a heading held back from export.
I have a capture template that saves tasks about the document 
under a * Tasks :no-export: heading.  To keep the agenda sane, I 
don't add the file.  Instead, I show buffer local tasks with 
org-sidebar.

hth,
Tom

-- 
Thomas S. Dye
https://tsdye.online/tsdye

Re: How to organize tasks about Worg within Worg documents

[Adam Porter]

Hi Tom,

On 3/29/24 18:30, Thomas S. Dye wrote:
> Here's another potential solution that I find useful.
> 
> d. Keeping tasks under a heading held back from export.
> I have a capture template that saves tasks about the document under a * 
> Tasks :no-export: heading.  To keep the agenda sane, I don't add the 
> file.  Instead, I show buffer local tasks with org-sidebar.

Yes, that's a good solution if we want the tasks hidden from the 
exported HTML on Worg.  I'm not sure if we do want that; that may be 
another minor policy decision to be made.  (Maybe it's not a big deal, 
but a bit of consistency in this regard would make Worg seem more 
serious and polished, which might encourage more contribution.)

Re: How to organize tasks about Worg within Worg documents (was: Re: [Worg] CSS improvements)

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

> Using a normal heading for a task would "commandeer" the structure of 
> the document, which I think is a real problem.

Not really. If some section is incomplete, marking it "TODO" means that
it should be completed. And the details might be listed in the logbook
notes, for example. The section name itself does not necessarily have to
details what needs to be done.

We have multiple instances of such "TODO" items in WORG, some also
include comments on what should be done.

On the other hand, inlinetasks are more concrete and immediately mark
both where exactly and what needs to be done.

> ISTM that there are a few potential solutions:
>
> a. Using inline tasks...
>
> b. Using commented lines...
>
> c. Keeping tasks in a separate file...
> ...

"Thomas S. Dye" <tsd@tsdye.online> writes:
> d. Keeping tasks under a heading held back from export...

> ...

Adam Porter <adam@alphapapa.net> writes:

> Regardless of the decision, I do think that having this stated as a 
> policy somewhere would be helpful.
>
> WDYT?

I am not 100% sure if we need to constrain "TODO" items to one or
another style. Global todo list, marking existing sections as TODO, and
inlinetasks all may have their place depending on the situation.

The policy we may want to set is whether "TODO" keywords and notes
should be displayed to all the users. WORG has this set all over the
place - some TODO headings are marked to be not exported, some TODO
keywords are hidden via #+options: todo:nil, some notes are placed into
# comments.

May we have some kind of css-based toggle that will enable "developer
mode", revealing all the todo keywords, inlinetasks, and notes? Then, we
hide the "unfinished" parts from users by default, but let them see what
can be contributed?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: How to organize tasks about Worg within Worg documents

[Adam Porter]

On 3/30/24 05:47, Ihor Radchenko wrote:
> Adam Porter <adam@alphapapa.net> writes:
> 
>> Using a normal heading for a task would "commandeer" the structure of
>> the document, which I think is a real problem.
> 
> Not really. If some section is incomplete, marking it "TODO" means that
> it should be completed. And the details might be listed in the logbook
> notes, for example. The section name itself does not necessarily have to
> details what needs to be done.
> 
> We have multiple instances of such "TODO" items in WORG, some also
> include comments on what should be done.
> 
> On the other hand, inlinetasks are more concrete and immediately mark
> both where exactly and what needs to be done.

You make a good point: for some cases, an entire section/heading may 
need "to be done," so giving the whole heading a TODO makes sense.  For 
other tasks, an inline one would be more appropriate.

> I am not 100% sure if we need to constrain "TODO" items to one or
> another style. Global todo list, marking existing sections as TODO, and
> inlinetasks all may have their place depending on the situation.
> 
> The policy we may want to set is whether "TODO" keywords and notes
> should be displayed to all the users. WORG has this set all over the
> place - some TODO headings are marked to be not exported, some TODO
> keywords are hidden via #+options: todo:nil, some notes are placed into
> # comments.
> 
> May we have some kind of css-based toggle that will enable "developer
> mode", revealing all the todo keywords, inlinetasks, and notes? Then, we
> hide the "unfinished" parts from users by default, but let them see what
> can be contributed?

I like the idea of a visual toggle very much, so I'm certainly in favor 
of that.

I'm not sure that we must have a constraint on the way TODOs are 
written, but having some limitations on or conventions about it might 
make such a visual toggle easier to implement (as well as other tools 
one might use to collect and visualize tasks across the project).

Re: How to organize tasks about Worg within Worg documents

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>> May we have some kind of css-based toggle that will enable "developer
>> mode", revealing all the todo keywords, inlinetasks, and notes? Then, we
>> hide the "unfinished" parts from users by default, but let them see what
>> can be contributed?
>
> I like the idea of a visual toggle very much, so I'm certainly in favor 
> of that.
>
> I'm not sure that we must have a constraint on the way TODOs are 
> written, but having some limitations on or conventions about it might 
> make such a visual toggle easier to implement (as well as other tools 
> one might use to collect and visualize tasks across the project).

What we may do is the following:
1. Make sure that we stick to the recommended todo keywords, so that
   todo keywords have a known-in-advance class in html export.
2. Put notes into LOGBOOK drawers (set `org-log-into-drawer' in WORG
   dirlocals)
3. Change `org-html-format-drawer-function' during publishing to mark
   the LOGBOOK drawers with a distinct class.
4. Enable org-inlinetask library during publishing.

Then, the CSS switch will involve toggling visibility of (1) todo
keyword classes; (2) inlinetask class; (3) LOGBOOK drawer class.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: How to organize tasks about Worg within Worg documents

[Adam Porter]

On 4/1/24 06:34, Ihor Radchenko wrote:

> What we may do is the following:
> 1. Make sure that we stick to the recommended todo keywords, so that
>     todo keywords have a known-in-advance class in html export.
> 2. Put notes into LOGBOOK drawers (set `org-log-into-drawer' in WORG
>     dirlocals)
> 3. Change `org-html-format-drawer-function' during publishing to mark
>     the LOGBOOK drawers with a distinct class.
> 4. Enable org-inlinetask library during publishing.
> 
> Then, the CSS switch will involve toggling visibility of (1) todo
> keyword classes; (2) inlinetask class; (3) LOGBOOK drawer class.

Sounds good to me!

Re: How to organize tasks about Worg within Worg documents

[Ihor Radchenko]

Adam Porter <adam@alphapapa.net> writes:

>> 2. Put notes into LOGBOOK drawers (set `org-log-into-drawer' in WORG
>>     dirlocals)
>> 3. Change `org-html-format-drawer-function' during publishing to mark
>>     the LOGBOOK drawers with a distinct class.
>> 4. Enable org-inlinetask library during publishing.
>> 
>> Then, the CSS switch will involve toggling visibility of (1) todo
>> keyword classes; (2) inlinetask class; (3) LOGBOOK drawer class.

I looked into this further, and found
exporters/taskjuggler/ox-taskjuggler.org

that has whole "TODO" subtrees hidden with :noexport: tag.

Such half-ready subtrees are not really ready for normal viewing and are
mostly a material for WORG hackers to work on. Not sure how they fit
into the discussed todo records and notes concept.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: How to organize tasks about Worg within Worg documents

[Adam Porter]

On 5/12/24 07:18, Ihor Radchenko wrote:

> I looked into this further, and found
> exporters/taskjuggler/ox-taskjuggler.org
> 
> that has whole "TODO" subtrees hidden with :noexport: tag.
> 
> Such half-ready subtrees are not really ready for normal viewing and are
> mostly a material for WORG hackers to work on. Not sure how they fit
> into the discussed todo records and notes concept.

Seems like a reasonable solution in that case.