aplteam / markapl Goto Github PK

At least MarkAPL.md carries embedded parameters it should not carry!

Cider's user guide is an example: open it and change the caption of 2.6.14 from Git status to Git and the number 2.6.14 will be removed from the caption.

The key terms in a definition list should never be made an <abbr> tag.

HTML are not recognized when placed at the top of a document because MarkAPL insists (wrongly) even then on two empty lines.

When the currently running version of Dyalog comes with a command line parameter lx that gets a numeric left argument link lx="1 #.Run 1 then this would be executed.

This:

## Page <http://britishaplassociation.org/about-british-apl-association/>

is wrongly formatted: the whole line seems to become a link

It would be nice to have a syntax for check boxes.

Ideas:

[[ ]]

for un-ticked ones and

[[x]]

for ticked ones. This is however, another incompatible Markdown extension.

This markdown:

[parm]:numberHeaders = 6

# _Level One_

Leads to this:

1. Level OneLevel One

Note that the space between "Level" and "One" is essential for making the bug an appearance.

https://download.aplteam.com/MarkAPL.html

Multiple <<br>> tags in a table cell are not handled correctly.

Which means it cannot currently be used in any supported version.

I recommend saving it in 15.0 as that will soon be Dyalog's oldest supported version.

Try ]version path/MarkAPL.dws

The documentation should mention a trick that allows a TOC to show just one level.

Imagine you want to show just level 2. Specifying [parm]:toc = 2 won't do because it is interpreted as "up to two , including level 1.

The argument needs to be a vector, and with [parm]:toc = 2 2 we can achieve the goal.

According to the documentation this:

not it*alic

should not be considered markup. The asterisk should show verbatim. It does not, it injects an <em> tag.

The same might be true for ** and _ and __.

On the key term they work.

This is recognized by MarkAPL as a valid definition with special attributes:

[Link](#Headers {style="color:magenta;"})

Although this syntax is clear and consistent, the rest of the world insists on

[Link](#Headers){style="color:magenta;"})

Therefore this should be corrected.

Since in HTML there are never any multiple spaces this causes a mutilated document.

MarkAPL requires

[ ] off
[x] on
[X] ALSO ON

GitHub on the other hand uses

- [ ] off
- [x] on
- [X] ALSO ON

The syntax was added to MarkAPL only recently, so I think it is okay to change it.

Currently when Meddy is used to edit a GitHub wiki the links do not work. It would be very nice if they would work.

It would be nice to allow inserting page breaks into a Markdown document.

Maybe with a syntax like ::^ at the beginning of a line?

PanDoc support them. Taken from the PanDoc documentation:

Extension: superscript, subscript

Superscripts may be written by surrounding the superscripted text by ^ characters; subscripts may be written by surrounding the subscripted text by ~ characters. Thus, for example,

H~2~O is a liquid.  2^10^ is 1024.

If the superscripted or subscripted text contains spaces, these spaces must be escaped with backslashes. (This is to prevent accidental superscripting and subscripting through the ordinary use of ~ and ^.) Thus, if you want the letter P with ‘a cat’ in subscripts, use P~a\ cat~, not P~a cat~.

This markdown:

### Loading Tatin[^tatin]  packages

has unwanted consequences.

This is

*italic*

survives verbatim.

It's also not standard Markdown, and possibly not even extended Markdown I believe.

Single line SetText headers works fine.

Naturally something like

[]CompareThese](https://github.com/aplteam/]CompareThese)

can't work: the first ] is not recognized as the start of a user command but as a closing square bracket, destroying the syntax.

However, things are different with:

[`]CompareThese`](https://github.com/aplteam/]CompareThese"Link to CompareThese on GitHub")

Here the first ] should be ignored because it is part of an APL expression, so it cannot close the link definition.

These classes could be very useful:

.center
.left
.right
.red

1. Too long: Shorten it dramatically and put the complex stuff into the wiki.

2. Find a solution for the HTML page the ReadMe is linking to.

3. Look out for ! as ` !SourceForge

Currently there is no way to make a link open another document in a new Tab.

The argument that this is outdated and should not used does not hold:

Although this might be true for HTML pages, for PDFs the user expects it to be opened in a separate Tab.

Kramdown seems to be the only marser that supports this. Their syntax makes sense: it's a special attribute, for example:

[APL wiki](https://aplwiki.com){:target="_blank"}
```

This:

### Should be ## rather than ###

leads to

### Should be ## rather than

This:

|Col 1 |Col 2 |Col 3
|-|-|-
|Text 1 |Text 2 | `APL code that gets missing
|text 1 |text 2      | text 3

leads to this:

because of the missing (closing) `

The way special attributes need to be defined for links is not in line with the CommonMark definition.

Also, since the implementation of MarkAPL CommonMark has specified the way special attributes should be implemented if they are implemented at all. This specification is partly incompatible with MarkAPL 4.x.x.

The CommonMark specification has the advantage of allowing to assign special attributes to both list definitions as such (read <ul> and <ol>) but also the list items (<li>).

This leads to an unpleasant outcome:

> Para 1
>
> Para 2

when printed.

This: C:\Users\<⎕AN>\.cider\ results in:

C:\Users<⎕AN>\.cider/

Note that C:\Users\\<⎕AN>\.cider\ yields the same result!

HTML tags within paragraphs etc. survive untouched. This is the result of a misunderstanding caused by the original Markdown documentation which stated that Markdown allows you to write about HTML without a headache.

However, the intention was to put HTML tags between single ticks rather than ignoring them as ordinary text.

As a result you cannot for example style a particular piece of text within a paragraph with something like this:

This is <div id="special">somehow styles</div> 

This is because it would be ignored.

I am wondering whether I should change this so that MarkAPL is in line with (most) other tools.

Causes a VALUE ERROR when MarkAPL is not used as a Tatin package

[^acre]: The project manager acre:<<br>>
<https://github.com/the-carlisle-group/Acre-Desktop/wiki>

Is formatted wrongly: the link seems to become a separate paragraph. Removing the colon in acre:<<br>> fixes the problem

Has no effect anymore anyway.

Removing won't have an effect either because setting it will just be ignored.

Needs removing from the documentation as well.

Git uses

 - [ ] 

for un-ticked check boxes and

 - [x] 

for ticked check boxes. That seems to be a nice idea.

Ideally both, terms and definitions should accept them

It would be nice to be able to inject a page break into a Markdown document.

Maybe something like :::^?

MarkAPL supports short hands for bookmark links. This:

[](#Headers)

makes MarkAPL use #Headers as link text. It should be Headers instead.

Imagine a user is editing a large markdown document. She changes a line in the document and then wants the editor to update a preview. Currently the whole document must be converted. That can result in a significant delay depending on the size of the document.

With the proposed method, only the affected block could be rendered again, which should result in a significant performance improvement.

Such a method requires two arguments:

1. A ref pointing to a variable with the markdown
2. An index (single positive integer) pointing into the variable: the current row

It should return two positive integers:

1. Starting row: where does the block start the given index is part of
2. Number of rows: size of that block

This would be very useful for updating only one block in a large document rather than the whole document.