On 19-01-2020 10:30, Alex Peshkoff via Firebird-devel wrote:
On 2020-01-18 12:03, Mark Rotteveel wrote:
On 17-01-2020 15:00, Alex Peshkoff via Firebird-devel wrote:
On 2020-01-17 16:29, Mark Rotteveel wrote:
Hardly any of the documentation in the docs-folder have links, and
you can have links in Markdown.
No named paragraphs. I have no idea how to create a link to specific
paragraph in MD.
The GitHub-flavoured markdown uses
[<descriptive name>](#<section-name>), where <section-name> is the
lowercase form of the section title, with the spaces replaced by a
minus (-). It looks like that is the standardized form (though I'm not
100% sure of that).
Pandoc also supports: [<section title>], which I currently use with
Jaybird, but that isn't supported by GitHub.
With Markdown Viewer Webext for firefox
(https://github.com/KeithLRobertson/markdown-viewer) I've got for:
[ABC](#SQL Samples:)
[SQL Samples:]
the following result:
[ABC](#SQL Samples:) [SQL Samples:]
I don't understand what you're saying. Are you saying that works, or
that doesn't work?
It not working is not surprising though, because whitespace isn't
allowed in a URI (see RFC-2396 section 2.4.3), and will actually
introduce a link-title in what is specified in commonmark.
In any case in pandoc and GitHub markdown, the following will work:
[ABC](#sql-samples), and that syntax can be inferred from the original
markdown syntax from
https://daringfireball.net/projects/markdown/syntax#link and from the
commonmark specification https://spec.commonmark.org/0.29/#links . What
is in the (...) is a URI, and URI can include the anchor (or fragment
identifier), or be an anchor alone (same as <a href="#anchor">..</a>).
That is what RFC-2396 calls a "Same-document Reference".
(Yes, I have a section 'SQL Samples' in that document).
I.e. suggested appears to be non-standard extensions and IMO bad style
for us.
It is (see links above), the only thing that doesn't seem to be
specified is exactly how a section anchor is derived from the section
title (eg pandoc leaves a dot (`.`) in place, while GitHub removes it).
In fact, it doesn't even seem to specify that a section anchor should be
added.
However, yesterday I changed the Jaybird release_notes to a syntax that
works both in pandoc (which I use the generate the release notes HTML
variant) and in the GitHub renderer.
Compare
https://raw.githubusercontent.com/FirebirdSQL/jaybird/master/src/documentation/release_notes.md
with
https://raw.githubusercontent.com/FirebirdSQL/jaybird/Branch_2_1/src/etc/release_notes.html
I've agreed that MD is much better for reviewing compared with
tool-written html. If we want to optimize our docs for good reviewing
let's go in this direction. In other aspects HTML appears better.
I think choosing a single format is preferable over the current state
which has at least three formats:
* Plain text with a non-standard syntax (both with and without .txt
extension)
* Plain text with markdown syntax
* HTML with a variety of codestyle, applied formatting (style), etc.
And while all three can be viewed acceptably locally (although one will
require a browser to render), only the first two types can be viewed
acceptably directly from the GitHub, which I think is very handy if you
want to link to it.
Compare:
*
https://github.com/FirebirdSQL/firebird/blob/master/doc/README.DiskSpaceAllocation
*
https://github.com/FirebirdSQL/firebird/blob/master/doc/README.modern_cpp.md
*
https://github.com/FirebirdSQL/firebird/blob/master/doc/README.build.mingw.html
Mark
--
Mark Rotteveel
Firebird-Devel mailing list, web interface at
https://lists.sourceforge.net/lists/listinfo/firebird-devel
