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

[Ihor Radchenko]

Adam Porter  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"  writes:
> d. Keeping tasks under a heading held back from export...

> ...

Adam Porter  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 .
Support Org development at ,
or support my work at 

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

[Thomas S. Dye]

Aloha all,

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

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: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter  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 .
Support Org development at ,
or support my work at 

Re: [Worg] CSS improvements

[Adam Porter]

On 3/28/24 08:18, Ihor Radchenko wrote:

Adam Porter  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  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 .
Support Org development at ,
or support my work at 

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  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 .
Support Org development at ,
or support my work at 

Re: [Worg] CSS improvements

[Adam Porter]

On 3/26/24 09:48, Ihor Radchenko wrote:

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

[David Rogers]

Adam Porter  writes:

On 3/24/24 03:56, Ihor Radchenko wrote: 
Adam Porter  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

[Ihor Radchenko]

Adam Porter  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 .
Support Org development at ,
or support my work at 

Re: [Worg] CSS improvements

[Adam Porter]

On 3/24/24 03:56, Ihor Radchenko wrote:

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

[Dr. Arne Babenhauserheide]

Ihor Radchenko  writes:

> Adam Porter  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" "?"))

# 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


signature.asc
Description: PGP signature

Re: [Worg] CSS improvements

[Ihor Radchenko]

Adam Porter  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 .
Support Org development at ,
or support my work at 

Re: [Worg] CSS improvements

[Adam Porter]

On 3/23/24 09:49, Ihor Radchenko wrote:

Adam Porter  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  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 .
Support Org development at ,
or support my work at