Changed {} to § in Markdown for function arguments

[sebasguts]

No description provided.

[codecov]

Codecov Report

Merging #190 into master will not change coverage.
The diff coverage is 100%.

@@           Coverage Diff           @@
##           master     #190   +/-   ##
=======================================
  Coverage   67.74%   67.74%           
=======================================
  Files          13       13           
  Lines        2108     2108           
=======================================
  Hits         1428     1428           
  Misses        680      680

Impacted Files	Coverage Δ
gap/Markdown.gi	97.7% <100%> (ø)	⬆️

[oysteins]

Is it necessary to have § at both the beginning and the end of an argument, not just the beginning? An argument name must be a valid GAP identifier, so it should be possible to detect where it ends.

[sebasguts]

Indeed, that would be possible, but a bit harder to implement. I will see if I get it done quickly, but first I want to have a new release that fixes #189

[fingolfin]

This seems rather arbitrary to me... perhaps we should simply revert this code for now, make a release, and then take our time to consider the problem more carefully?

[sebasguts]

@fingolfin allright, though

[sebasguts]

@mtorpey suggested to use double-backticks `` for arguments.
@oysteins @fingolfin What do you think?
Another option would be to do $foo, without a closing `$`

[mtorpey]

Hi folks!

As @sebasguts says, my suggestion would be double backticks for arguments (<A> tags) and single backticks for other code (<C> tags), as shown:

If the argument ``inter`` is set to `true`, then an interactive prompt will be created.

I believe this would keep the code clean, readable, and would not introduce any unnecessarily heavy distinction between normal code and arguments. The point of Markdown, for me, is that it just looks like readable plaintext and not a markup language at all, and symbols like @ and § and $ tend to spoil that a little bit.

That said, I'd be happy with a symbol like $ either at the beginning, or at the beginning and end -- this would still be nice-looking enough, and certainly much better than <A></A>, which is the best option at the moment.

I'm not a fan of §, partly because it's non-ASCII, but also because it's difficult to type on silly British keyboards.

[olexandr-konovalov]

Backticks for <C> elements would be great, so I very much agree with @mtorpey that we should keep them for this purpose. In this case, double backticks for <A> sound good for me too.

I don't like $ since many of us will unconsciously parse it to LaTeX notation, so that will ultimately cause confusion.

[fingolfin]

This PR obviously needs to be rebased now.

I am a bit concerned about the idea of using double backticks, because I fear this might introduce a serious incompatibility with regular MarkDown, and I am still dreaming of us using a proper MarkDown parser with minor extensions at some point (e.g. by adapting https://github.com/commonmark/cmark).

I share the concern about $ -- intuitively I'd expect that to be an alias for <M> ... <M>.

And then § is indeed not ASCII, which is also problematic, though the more important concern here is how difficult it is to actually type it.

One thing we could do is that if we see a single backtick quoted identifier, we could lookup whether it is an argument name, and then use that to decide whether to emit <C> or <A>. I'd expect that cover 95% of all cases just fine...?

Finally, and in the end, I just think that typing <A>foo</A> is not that terrible... ;-)

[mtorpey]

I like the sound of single backticks for both and , with the computer working it out from context. The fewer technical things we have to worry about when writing the doc, the better!

[sebasguts]

Yep, it needs to be rebased, but atm I am not sure if we should rather close it for now, or come up with something sensible. To be honest, in most cases we know the identifiers for arguments. So maybe we should just look for them and put them in <A> tags, without any "markdown" indication? This can of course cause more troubles.

[olexandr-konovalov]

@sebasguts This will cause massive problems when identifiers are real words.

[sebasguts]

Indeed, that's why I am quite reluctant to do it. We could also use backticks for identifiers, and if they are identifiers, we make them <A> instead of <C>. What about this?

[olexandr-konovalov]

Trying to summarise the discussion, single backticks for <C> elements and, if possible, automated inferring of <A> elements from those denoted by single backticks sounds the most sensible way to go. If inferring is hard, I will be happy with writing <A> as well.

[olexandr-konovalov]

@sebasguts by "identifiers" you mean "arguments"? You can also check if something is a keyword, and convert false in backticks to <K>false</K> etc.

[sebasguts]

@alex-konovalov Yep, by identifiers I mean argument names. I will also do the keywords. I guess we can trust GAPInfo.Keywords here?

[fingolfin]

So I guess this can essentially be closed? Perhaps after extracting an issue or two to remind us about the content and result of the discussion?

[fingolfin]

Just filed issue #207, so now closing this PR