Add table formatting for constant lists

[haszi]

@Girgias This is an attempt to implement formatting constant lists as tables. While most of it works fine, the format_variablelist() function has an issue I'm hoping you might be able to help me with. Namely that I'm inserting a header row as a string here which includes the hardcoded strings Constants and Description. Is there a way to access the language specific strings of the appropriate entities (&Constants; and &Description;).

[Girgias]

There is language data in phpdotnet/phd/data/langs but I'm not sure how this is accessed :/ let me have a look

[Girgias]

Seems doing $this->autogen($key, $lang) fetches the relevant entry if it exists?

[haszi]

Seems doing $this->autogen($key, $lang) fetches the relevant entry if it exists?

That was it, thanks!

I've added three additional commits:

• the first fixes the issue I've already noticed while updating the curl_getinfo() constant tables in the translations where the renderer was complaining about a missing language .ini file. It turns out that whatever the directory is called will be added to .manual.xml as xml:lang's value and the renderer takes that as the language. Unfortunately the default directories include a doc- prefix which this commit removes
• added Description and Constants to those languages' .ini file for which I've found a repository (and a language-defs.ent file)
• added the function you've suggested ($this->autogen($key, $lang)) to pull the language specific words for the headers. Works like a charm

With this PR, Phd will generate tables out of <variablelist>s when a role="constant_list" is attribute/value pair is used on it. One limitation of this implementation is that the header row is fixed to having only two columns (Constants and Description). Let me know what you think.

[Girgias]

Haven't tried this locally yet, but this looks good :) would probably also allow use to automatically generate links for <constant> tags when all of the roles are set and so there is a way to index the constant definitions :)

I've pinged translators so they can have a look at the lang data.

[Girgias]

Just had a look at it locally, and looks good :)

I do wonder maybe if we should move the type information into another term tag for it to be rendered as a column too, but that's going to require modifying a lot of doc pages :/

[haszi]

Just had a look at it locally, and looks good :)

I do wonder maybe if we should move the type information into another term tag for it to be rendered as a column too, but that's going to require modifying a lot of doc pages :/

I was thinking about that too and a separate column could look better for types. Some constant list tables also have a notes column (mostly used as a changelog for individual constants) which I think is mostly a waste of valuable screen space. But as long as the constants are grouped in some logical manner, a separate column for types should be fine.

Unless we do this: :-)

Constants	Type	Description
CURLE_OK	int	All fine. Proceed as usual.
CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256	int	Base64-encoded SHA256 hash of the remote host's public key. The transfer will fail if the given hash does not match the hash the remote host provides.

[Girgias]

I think having the changelog (for addition/removal) can just be in the description. A whole column for it is wasteful IMHO.

Also I realised, considering the rendering only works when the markup is changed to add the role attribute, changing the markup at the same time to move the type info into a <term> tag should also be fine.

[haszi]

I think having the changelog (for addition/removal) can just be in the description. A whole column for it is wasteful IMHO.

Great, I was thinking the same. :-)

Also I realised, considering the rendering only works when the markup is changed to add the role attribute, changing the markup at the same time to move the type info into a <term> tag should also be fine.

I'll try to check most extensions in the next few days to see what kind of workload it would be to get all constants on the constants pages and convert them to the three column <variablelist role="constant_list"> format. Hopefully there isn't too much variation in formats and I can whip up a script or two for this. Based on what you've said about them the cURL constants will be a great testing ground. :-)

[haszi]

Haven't tried this locally yet, but this looks good :) would probably also allow use to automatically generate links for <constant> tags when all of the roles are set and so there is a way to index the constant definitions :)

Another thing that just occurred to me is that it would be great if we could search for specific constants using the manual's search function and it would take us straight to the constant.

Also related to search but not to constants, it'd be great if searching for any of the reserved words (e.g. function, use, string, etc.) would go straight to the page discussing them instead of the Related snippet found for... page.

[haszi]

Haven't tried this locally yet, but this looks good :) would probably also allow use to automatically generate links for <constant> tags when all of the roles are set and so there is a way to index the constant definitions :)

I've just realized that there is an issue with both using XInclude and linkable constants. For constants to be linkable each of them needs to have a xml:id. For XInclude to work constants in the linked constant lists/tables cannot have xml:ids because these would be resolved with said ids and lead to duplicate ids.

Is there any other way to the constant lists like XInclude is doing or is there another way to link to individual constants? Or is there a way for XInclude's xpointer to exclude xml:ids somehow?

[Girgias]

Yeah, having the search work would be great. My understanding is that the search DB is generated during the indexing phase (the first run of PhD) which is a special "renderer".

I suppose it would be easy to add the reserved keywords to it, either by using an XML PI or just hard coding them in the constructor of the indexing render 🤔

Not sure about XInclude, I asked @nielsdos about it and he'll reply to me (or here) when he has time :)

[nielsdos]

I'll have a better look at home, but from https://www.w3.org/TR/xinclude-11/#attribute-copying I read:

Also, while attributes in xml: namespace are not copied, it is possible to use the set-xml-id attribute to change xml:id attributes on XIncluded elements.

[nielsdos]

I'll have a better look at home, but from https://www.w3.org/TR/xinclude-11/#attribute-copying I read:

Also, while attributes in xml: namespace are not copied, it is possible to use the set-xml-id attribute to change xml:id attributes on XIncluded elements.

But looks like libxml2 implements the 2003 spec of XInclude, not the newer XInclude version 1.1 that introduced the set-xml-id attribute. In that case I don't see a workaround except applying custom processing or XSLT. Or if you can solve it by including the children instead of the <constant> element itself that may work too depending on your use-case.

[haszi]

Thanks for checking on this. It would have been great to use set-xml-id but such is life. :-)

XSLT's for-each could be used for this too but I don't think the current DTD includes anything XSLT related. Unfortunately I wouldn't even know where to begin to add that either.

I think I'll delete the ids for now and will come back to this when working on adding a link to each constant (like how functions are linked) and making them searchable.

[haszi]

@Girgias please don't add the constant_list role to any <variabelist>s yet as nested roles will result in corrupted tables.

I was originally thinking about refactoring the role property to an array so that nested roles could be used for custom rendering but I'm already working on this to fix the bug/limitation on nested roles.
I noticed this issue while moving all translations' cURL constants to their constants pages when one of the descriptions included a <literal> tag that the renderer added a code role to. And as the role property belongs to the format (not to an element) object the parent element's constant_list role was overwritten.

Is there a test suite for Phd somewhere I could test my changes on? I've found a handful of tests in the Phd directory but there seems to be way more functionality to Phd than this.

[Girgias]

@Girgias please don't add the constant_list role to any <variabelist>s yet as nested roles will result in corrupted tables.

I was originally thinking about refactoring the role property to an array so that nested roles could be used for custom rendering but I'm already working on this to fix the bug/limitation on nested roles. I noticed this issue while moving all translations' cURL constants to their constants pages when one of the descriptions included a <literal> tag that the renderer added a code role to. And as the role property belongs to the format (not to an element) object the parent element's constant_list role was overwritten.

Is there a test suite for Phd somewhere I could test my changes on? I've found a handful of tests in the Phd directory but there seems to be way more functionality to Phd than this.

I wasn't planning on adding it yet, as I'm leaving it to be your project in some way.

I saw you found the test suite already, which IIRC uses the php-src run-tests.php script