Some env content provided does not make it into the documentation

[mmattel]

There seems to be an issue that some content that is present here in the repo does not make it into the documentation.

screenshot provided by @dragonchaser

outcome on the web (admin docs)

As you can see, the type and the default are missing, while the description is present.

Another one is FRONTEND_CHECKSUMS_SUPPORTED_TYPES where type and the default are missing too.

It seems that something (tm) is happening inbetween the source and the generated adoc table. admin docs does nothing with it and just includes that file.

[wkloucek]

@mmattel looks like the default value is not properly escaped: https://github.com/owncloud/ocis/blame/docs/services/_includes/adoc/frontend_configvars.adoc#L289-L294

Could you please give a properly escaped example for this?

|`FRONTEND_CHECKSUMS_SUPPORTED_TYPES`
| 
a| [subs=-attributes]
[sha1 md5 adler32] 
a| [subs=-attributes]
Supported checksum types to be announced to the client (e.g. md5)

EDIT:
same applies to the other example: https://github.com/owncloud/ocis/blame/docs/services/_includes/adoc/thumbnails_configvars.adoc#L123-L128

|`THUMBNAILS_RESOLUTIONS`
| 
a| [subs=-attributes]
[16x16 32x32 64x64 128x128 1920x1080 3840x2160 7680x4320] 
a| [subs=-attributes]
The supported target resolutions in the format WidthxHeight e.g. 32x32. You can provide multiple resolutions separated by a comma.

[dragonchaser]

could it be related to the fact that both fields are slices ([]string)

[mmattel]

Found the issue 😅 we need to adapt the adoc export.

Reason
We need in the table cell the Antora directive to go for antora language but disable attribute resolution a| [subs=-attributes]. When doing so [ ] becomes as part of the text in the next line different meaning.

Solution 1
To solve this, we need to special escape IN THAT CELL TYPE the square opening and closing brackets in following way:

if string contains "blank [ character" then replace [ with +[
if string contains "character ] blank" then replace ] with ]+

Example replacement (note the leading and trailing blanks):
[16x16 --> +[16x16
7680x4320] --> 7680x4320]+

No replacement would be when (blank between bracket and character):
[ 16x16
7680x4320 ]

Solution 2
Similar as above, we need to put the content written into pass:[bla bla] which passes thru all the stuff.

Solution 1 requires adaption of the rules which is more effort
Solution 2 is just a small change in the docs/templates/ADOC.tmpl in this repo

I will create a PR with solution 2 and @dragonchaser will do a local render test and checks the output for success.

[dragonchaser]

We need to add a specific regexp to solve this here: https://github.com/owncloud/ocis/blob/master/docs/helpers/adoc-generator.go.tmpl#L97 to replace [ and ] according to the rules @mmattel mentions above.