Re: New ikiwiki tags

[izzyb <izzyb@xxxxxxxxxxxxxxx>]

Yeah [[!color]] is an existing directive that can be used but I don't 
like that style; especially with the text being in a variable like 
that.  ikiwiki uses the wikilink tags with a leading ! as directives.  
so [[!directive]] is the existing syntax for extensions in ikiwiki.  
Using that syntax makes the most sense, but I'd like to create a plugin 
that works as a wrapper around the content.

So something like [[!block]] and [[!end]] would be simplest I think, but 
I need to finish learning my way around how the existing system works.  
Perhaps we could specify the end mark as a attribute leaving the default 
a blank line.  Actually that might work on its own without an end tag.  
So [[!block]] would be in effect until the first line beginning with \n. 
The existing block format tag uses lines beginning with 4 spaces or a 
tab iirc.  So That would work with the existing markdown syntax without 
a need for an end tag.  The \n would be the end tag then.

I could make it so you can specify an end tag for content that has 
issues with that format. So:

[[!block end='!end' class=code]]
    if ($done) {
        exit();
    }
[[!end]]

Using indenting on the code blocks would be enough in that case though, 
so you could skip specifying an end block.  I need to play with this 
some to see what is possible.  The end result though is the directive 
tag could be stripped or left in and wont be too much of a distraction 
in the content even if left as is.  For the html output, it'd likely 
wrap that in a div with a class=code attribute and css would take care 
of the layout details.  You could specify any attribute supported by a 
<div> block then, but discouraging the use of style= chunks would be 
ideal.  ie, the content should only be tagged for styling, not embedded 
with styling or it'll be hard to read in plain txt output.

Using ! as markup on its own would mean extending the markdown 
processing itself and wouldn't be as flexible.  I've been using multiple 
%defines% for different types of output in the documents I've created in 
pmwiki.  So using a single markup that applies a class or id to the 
content makes it easy to specify the layout in css where it belongs.  
Not sure how difficult it is to extend the markup compared to just using 
the built in [[!directive]] syntax already used by ikiwiki.  I haven't 
looked into the coding details yet, but I think it auto detects and 
looks for a plugin to run based on the [[!directive]] syntax.

It also be useful for things like a [[!chess]] plugin that can behave 
like the pmWiki (:chess:) markup.  Here's some links to ikiwiki docs 
worth looking at to understand its design in this regard.

https://ikiwiki.info/plugins/contrib/cowsay/

I don't like the use of the text= directive in this.

https://ikiwiki.info/ikiwiki/directive/color/

Same here. and don't like the direct specifying of colors inline like 
this. Would be better to use a class or id so css can handle it. Would 
make it cleaner to read in plain text I think.

https://ikiwiki.info/ikiwiki/directive/

This explains the [[!derective]] syntax built in.  And the """ or ''' 
for allowing multi line content for attributes.  its useful, but again I 
don't like needing to put the content into an attribute. would like the 
content after the tag up to an end marker or \n on a blank line to be 
the effected content.  Think that would be less intrusive for people 
reading the raw repo data.

https://ikiwiki.info/plugins/localstyle/

This would be useful for allowing different styling rules for different 
sections of the wiki.

I'm hoping to get a working wiki up this weekend so we can play with it 
to test out different ideas and see what is possible. Ideally we want 
the markup to be easy to work with and unobtrusive in raw format while 
still allowing for advanced layouts in html output.

...Izzy

On 2023-05-06 07:53, jrmu wrote:
> Greetings teammates,
>
> I spoke with izzyb about the tags he wanted to use for ikiwiki.
>
> We both agreed we want to avoid stylistic directives like these:
>
> [[!color  foreground=white background=#ff0000 text="White text on red background"]]
>
> These tend to be html specific and will clutter the repo with unreadable
> markup, as well as make theming inconsistent because stylesheets will
> get overridden and editors won't remember to maintain these.
>
> I think we agreed to stick with semantic tags.
>
> Izzyb requested this style of directive:
>
> [[!block class=warning]]
>
> He'd use that to format a block of text as a warning.
>
> I had suggested using [[!warning]], or better yet even !!Warning.
> ! could be caution, !! could be warning, and !!! could be danger
>
> The benefit of my shorter version is that it would not require e any
> filtering at all because !! Warning is pretty self explanatory and uses
> only typographic marks.
>
> Izzyb however believed that [[!block class=warning]] would be easier to
> filter and process.
>
> Full chat logs below:
>
> 06:27 <~jrmu> izzyb: I was thinking about the markup last night, can we avoid stylistic directives like these: [[!color  foreground=white background=#ff0000 text="White text on red background"]]
> 06:28 <~jrmu> These tend to be html specific and I've had at least two teammates say they don't want the repo to be cluttered with this type of markup. The other reason is because, it's also a style override and is going to cause us problems later because stylesheets won't be consistently applied
> 06:29 <~jrmu> It would be best if we can stick with just semantic tags, it will also make it much easier for you when theming because these kind of style directives tend to go unmaintained
> 06:29 <~jrmu> (eg, if you later change your css background to white, that text is going to end up appearing invisible)
> 06:29 < izzyb> morning jrmu. yeah thats why id and class would be better
> 06:30 < izzyb> so you could just tag it and make such changes via css
> 06:31 <~jrmu> good morning izzyb. OK yeah good
> 06:31 < izzyb> thats whats wrong with most html, people use it to do style stuff that belongs in css
> 06:32 < izzyb> so [[!block class=warning]] would be how I'd like to us it
> 06:32 <~jrmu> do you think perhaps something like [[warning]] might be even shorter?
> 06:32 < izzyb> well, that could be done but then would need a filter for each one
> 06:33 <~jrmu> Yeah. I'll ask IanJ and mkf later, what they think. At least for me [[warning]] looks more human readable
> 06:33 < izzyb> itd be better to have a single directive with class tags
> 06:33 < izzyb> well that is a wikilink like that though
> 06:33 < izzyb> [[!directive]] is how ikiwiki is designed
> 06:33 <~jrmu> oh yes, I forget it overloads
> 06:34 < izzyb> where you have named directives starting with a !
> 06:34 <~jrmu> true yes
> 06:34 < izzyb> so having a single dirrective with a class our id would allow css to deal with the details of how that looks
> 06:35 < izzyb> which would make it cleaner
> 06:35 < izzyb> and easier to filter out if ianj wants to with no harm to the content
> 06:36 <~jrmu> maybe [[!warning]]?
> 06:36 <~jrmu> or even !Warning message here
> 06:36 < izzyb> but then your filter has more work. you need to find multple directives
> 06:36 <~jrmu> ! could be caution, !! could be warning, and !!! could be danger
> 06:37 <~jrmu> Yeah, I'll ask IanJ what he thinks, see which he prefers
> 06:37 < izzyb> yeah, then you need to make sure your listening device understands the additional markup
> 06:37 <~jrmu> the benefit I think for IanJ is then he wouldn't have to do anything I think
> 06:37 <~jrmu> he'd just leave !!Warning message here completely untouched
> 06:37 < izzyb> making it a single directive that can be ignored and stripped or left in for the reader to intemperate makes more sense to me
> 06:37 <~jrmu> as I think he wants to avoid doing much filtering
> 06:38 < izzyb> yeah he's not going to be able to get away without some at least
> 06:38 < izzyb> so making it easier to filter makes more sense to me
> 06:39 <~jrmu> gotcha, I'll relay that to him
> 06:39 < izzyb> so a single directive as appose to multiple specific dirrectives makes more sense
> 06:39 <~jrmu> Actually, on second though, I would personally prefer the typographic marks myself
> 06:40 < izzyb> the thing I don't like at the moment is the current approach puts the content inside the dirrective in a text='content' type thing
> 06:40 <~jrmu> because if I were to offer access via email, I might not have time to write a full fledged filter
> 06:40 < izzyb> Itd be better if the content was kept separate from the directives
> 06:40 < izzyb> so the directives could be just dropped
> 06:40 <~jrmu> and !!Warning to me would look less confusing than [[!warning]], which is also less confusing than [[!block class=warning]]
> 06:40 < izzyb> leaving the uneffected content then
> 06:41 < izzyb> yeah but you'd need one for every type of content then
> 06:41 <~jrmu> yeah
> 06:42 < izzyb> [[!block class=config]] would work better as its only one dirrective to filter or you could leave in and it could be understood by the user as is
> 06:44 <~jrmu> I'll go ahead and summarize the discussion over on codeforce@xxxxxxxxxx
> 06:44 <~jrmu> to make sure everyone is ok with the decision