projectmallard / mallard-ducktype Goto Github PK

In parse_file(), in parser.py, open() is called without an encoding parameter. According to the open documentation the default encoding is platform dependent. It seems that when building RPMs in Koji (for Fedora), the platform encoding is ascii, which causes any non-ASCII sequence to raise an error, like in the dbus ducktype documentation (search for UnicodeDecodeError).

I guess that ducktype should specify an encoding, such as utf-8.

Use duck to write yelp document is simple, and I want to know is there any plan to let meson support duck files in gnome.yelp module?

When I use @include on the index, the @include is not converted properly from Ducktype into Mallard and therefore when I create HTML with Pintail, the index page is blank.

If I have some Ducktype:

Interface files for public API should be installed to
$code($var($$(datadir$))/dbus-1/interfaces) so that other services can load
them. Private APIs should not be installed. There should be one file installed
per D-Bus interface, named after the interface, containing a single top-level
$code(<node>) element with a single $code(<interface>) beneath it. For example,
interface $code(com.example.MyService1.Manager) would be described by file
$file($var($$(datadir$))/dbus-1/interfaces/com.example.MyService1.Manager.xml):

the following Mallard gets produced:

<p>Interface files for public API should be installed to
  <code><var>$(datadir))/dbus-1/interfaces</var> so that other services can load
them. Private APIs should not be installed. There should be one file installed
per D-Bus interface, named after the interface, containing a single top-level
<code>&lt;node></code> element with a single <code>&lt;interface></code> beneath it. For example,
interface <code>com.example.MyService1.Manager</code> would be described by file
<file><var>$(datadir))/dbus-1/interfaces/com.example.MyService1.Manager.xml</var>:</file></code></p>

Note that the <var> element doesn’t get closed after $(datadir), there’s a spurious ) after $(datadir), and the <code> element doesn’t get closed either.

You can see a rendered example here.

To be clear, the $(datadir) is supposed to be literal; I think the escaping on it is right, but I’m not 100% sure.

There's any Ducktype validator?
How can I debug what I'm writing? AFAIK now I must first convert to xml using mallard-ducktype and then use yelp-check validate. But this is cumbersome, as I have to check the .page file and then work on the .duck file.

I also wonder what's the adoption status of Ducktype. I think that all GNOME projects use the Mallard spec only, right? What is preventing the use of Ducktype?

Normally, sections are automatically closed when new sections at the same or higher level open. This is fine, because normal content isn't allowed between or after sections. Except that the links element is allowed after section content. So if you're doing complex stuff with links, you need to be able to do post-section content. Do this:

== Section One

This is section one.

== Section Two

This is section two.

==

[links type="guide"]

Test case:

= Inline Test
Let’s put nested non-syntax brackets in an inline: $code(AddContact(ss) → (u)).

Test case:

= Multi-code test

== Some title

[code]
  Some code

== Some other title

[code]
  Some other code

We should have a way to put in comments that aren't parsed (not just the Mallard comment element).

Trailing spaces at the end of lines in .duck files can sometimes affect the XML that is produced by the parser, and trailing spaces should be removed.

For example, a simple .duck file like this:
= Index
[style=task]
@desc A short description of this page
@revision[date=2015-05-05 status=draft]

This is a simple page.

with a trailing space in "Index " will result in a trailing space at the end of "Index " in the staged XML.

@years 2017 gets parsed as <years>2017 </years> with random spaces on the end of it. The spaces should not be there. The @license block is followed by a blank line in my file.

Current parser requires that, to continue a heading title or subtitle, you have to indent to the level of the prefix, as in:

== The page title starts here
   And continues here. Note three spaces.

It's unambiguous with even one space.

== The page title starts here
 And continues here, even with one space.

Let's make that change.

I know that as twst suite is used now setuptools test however:

+ /usr/bin/python3 -Bm pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.9, pytest-6.2.3, py-1.10.0, pluggy-0.13.1
rootdir: /home/tkloczko/rpmbuild/BUILD/mallard-ducktype-1.0.2
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, asyncio-0.14.0, expect-1.1.0, cov-2.11.1, mock-3.5.1, httpbin-1.0.0, xdist-2.2.1, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, pyfakefs-4.4.0, freezegun-0.4.2, flaky-3.7.0, cases-3.4.6, hypothesis-6.10.1, case-1.5.3, isort-1.3.0
collected 0 items

============================================================================= warnings summary =============================================================================
mallard/ducktype/extensions/_test.py:33
  /home/tkloczko/rpmbuild/BUILD/mallard-ducktype-1.0.2/mallard/ducktype/extensions/_test.py:33: PytestCollectionWarning: cannot collect test class 'TestExtension' because it has a __init__ constructor (from: mallard/ducktype/extensions/_test.py)
    class TestExtension(mallard.ducktype.parser.ParserExtension):

-- Docs: https://docs.pytest.org/en/stable/warnings.html
============================================================================ 1 warning in 0.19s ============================================================================

The README file should show how to setup an environment for DuckType, as well as how to render a DuckType-formatted document to Mallard XML and/or HTML.

Current parser only allows info elements for pages and sections. Let's do them for block elements as well, anticipating MEP 0002.

Having a link inside a license doesn't seem to be working and it doesn't seem to be tested.

This input:

@license[>>https://creativecommons.org/licenses/by-sa/4.0/]
  This work is licensed under a
  $link[>>http://creativecommons.org/licenses/by-sa/4.0/](Creative Commons
  Attribution-ShareAlike 4.0 International License).

  As a special exception, the copyright holders give you permission to copy,
  modify, and distribute the example code contained in this document under
  the terms of your choosing, without restriction.

Produces this output:

License
This work is licensed under a $link[>>http://creativecommons.org/licenses/by-sa/4.0/](Creative Commons Attribution-ShareAlike 4.0 International License).

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

The word "License" is also styled as a normal paragraph. It should be the same style as "About".

The link from "@license[>>https://creativecommons.org/licenses/by-sa/4.0/]" does not seem to be used for anything.

Code blocks in Mallard still have inline parsing, unlike many other lightweight formats. This is intentional, so that you can still highlight and link and stuff in code blocks. But sometimes it's nice to have a no-parse segment if there's a lot of stuff to escape. Maybe a fenced mechanism? Would be nice to use a character that's already syntactically relevant. Perhaps triple-square-bracket?

[code]
[[[
I don't have to escape $dollor(signs) or
[markup]
that looks like blocks.
]]]