Proposing \* as pragma rule for comments?

[Mat]

I intend to post the following on github but wish to bounce it here first, in case I'm missing something.

(Frankly, I'm not even sure I'm using the term "pragma rule" correctly - am I?)

Thanks!

<:-)

----------------------------------------------------------------------------------------

Introduce \* pragma rule for comments:

I want to insert comments among macro defs and propose a new "pragma rule" (?) for this like so:

```

\* This is foo

\define foo()...

\* This is bar

\define bar()...

```

...multilines could perhaps be

```

\* This

    is

    foo  *\

```

It is obviously inspired by the CSS comments format with `/* rightward slashes */` - and it would of course be even better if we could use that right away.

Note: It *is* already possible to comment among macro defs like so

```

\define foo()

<!-- This is foo -->

\end

```

...but this is bad because:

The comment is less visible when *after* the title.

One must not use one-line macro defs.

The `<!-- ... -->` syntax is more complex than `/* ... */`

[@TiddlyTweeter]

Mat

Commenting on your comments on comments.

Comments are good.

One important role for them is to declare authorship.

If life were fair Mark S. would have a very high ranking on first copyright comment lines. At the moment he gets none.

Best wishes
Josiah

[Arlen Beiler]

I heartily agree, although, I would like to see the double forward slash used for single line comments and forward slash and star used as multi-line comments. Is there a reason why we cannot use forward slash? Maybe the double forward slash is already taken for italics.

--
You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidev+unsubscribe@googlegroups.com.
To post to this group, send email to tiddly...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywikidev.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/a8a487b5-ee7a-4a32-8405-fed9615c9ad1%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Mat]

Arlen Beiler wrote:

I heartily agree, although, I would like to see the double forward slash used for single line comments and forward slash and star used as multi-line comments. Is there a reason why we cannot use forward slash? Maybe the double forward slash is already taken for italics.

I assumed that \ is a general marker for pragmas and thus it'd be easy to implement \* 

The \ sticks with established TW syntax, whereas // is js and, as you note, conflicts with italics - at least psychologically.

Still, because we are allowed to use CSS (as opposed to js) in TW, I do favor /* .

...but the absolute optimal would be universal solution: Currently one must use <!-- --> mid tiddler, but it would be much better if whatever-is-decided could be used everywhere; among macro defs, in CSS and mid-tiddler.

Overall, considering how TW relies on building on other peoples stuff, it makes sense if the system encourages commenting by making it simple.

<:-)

[Mat]

I just did a quick test for a macro:

\define "(comm)
$comm$
\end

<<" hey>>

...i.e the name if the macro is "

Maybe this could be made to detect which environment it is in (in the macro def section, mid-tid or css).

It is obviously wikitext, which is pretty cool.

<:-)

[PMario]

Hi Mat,

\define foo()

<!-- This is foo -->

\end

Everytime this macro is processed, the comment has to be "parsed" just to be removed. ... comments outside macro code are ok, since global macros are parsed at the TW startup and "outside comments" are thrown away.

For simple macros, that's not a problem. ... but for "well documented macros" the documentation, can easily become bigger than the "executed" code. ... I'm talking about TOC like macros. ... There really should be docs, but it's a performance problem, with "recursive" macros.

So heavily commenting inside macros imo isn't the best idea. ... performance wise.

------------- techy stuff ...

The internal parse tree looks like this.

[
    {
        "type": "set",
        "attributes": {
            "name": {
                "type": "string",
                "value": "foo"
            },
            "value": {
                "type": "string",
                "value": "<!-- This is foo -->"
            }
        },
        "children": [],
        "params": []
    }
]

The rendered output is: 


That's not efficient for heavy docs inside the macros. ..

@Jeremy, ... What if we do create a new "comment" syntax for macros and do a sanitation run before we store the global macros in variables?? ... @Mat this proposal would be for $:/tags/Macro tiddlers only.

just some thoughts.
-mario

[PMario]

On Thursday, June 29, 2017 at 8:00:09 PM UTC+2, PMario wrote:

[
    {
        "type": "set",
        "attributes": {
            "name": {
                "type": "string",
                "value": "foo"
            },
            "value": {
                "type": "string",
                "value": "<!-- This is foo -->"
            }
        },
        "children": [],
        "params": []
    }
]

The rendered output is: 

Just to be correct. .. Rendering the output needs to examine the above parse-tree, convert it to a widget tree, like this:

{
    "type": "widget",
    "children": [
        {
            "type": "set",
            "attributes": {
                "name": "foo",
                "value": "<!-- This is foo -->"
            }
        }
    ]
}


and then create the output, by converting the "value" into html code, which results in:




-mario

[PMario]

For those who are interested:

<$set name="foo" value="<!-- This is foo -->">

creates this widget tree:

{
    "type": "widget",
    "children": [
        {
            "type": "set",
            "attributes": {
                "name": "foo",
                "value": "<!-- This is foo -->"
            }
        }
    ]
}

have fun!
mario

[Mat]

@PMario

good input.

\define foo()

<!-- This is foo -->

\end

... heavily commenting inside macros imo isn't the best idea. ... performance wise.

In my experience, the most important is to be able to comment just before the macro.

<:-)

[Mat]

Correcting an insinuation I made before:

I just discovered the /* ... */ syntax is not only for CSS but also for multiline js comments. (Yes, I realize I'm the only one who didn't know). So that would be terrific.

BTW, I wonder why html comments have <!-- this syntax -->

<:-)

[Ton Gerner]

Hi,

In many cases I insert 'comments' (mainly about the syntax for use) after \end and between triple backticks, e.g.:

\define slider (label,text)
...
\end

```
Use:

<<slider "label" "text">>
```

When you select/open a macro you directly see how to use it

Cheers,

Ton

[PMario]

On Thursday, June 29, 2017 at 8:33:02 PM UTC+2, Mat wrote:

Correcting an insinuation I made before:

I just discovered the /* ... */ syntax is not only for CSS but also for multiline js comments. (Yes, I realize I'm the only one who didn't know). So that would be terrific.

Yea. .. In TWclassic there where 3 types of "code block" syntax:

•  {{{ comment }}} ... for wikitext code block
  

•  /*{{{*/  .... for rendering comments in valid CSS tiddlers
• /* */ for making it invisible for the browsers CSS parser. So the whole thing is valid CSS
• {{{ .. to make it visible for the TW syntax parser and render the stuff as comment.
  

• <!--{{{-->  .... for rendering TW code in valid HTML text
• mechanism is similar to CSS

The problem with all those comments are. They are producing some "output", so they need work to be done, just to make them invisible again for the system where it's used.

So the 2 way "compilation" step, that I did suggest, may avoid this problem, but would introduce quite some complexity ...

-m

[PMario]

needed to fix some typos in the last post
-m