Format <seealso> values of -xml-config in the same way as <eqconfig> values of -xml-help

[eric-brechemier]

In tidy-help.xml, the output of tidy -xml-help, the <eqconfig> values include the initial dash and the format of the expected value:

<eqconfig>output-file: &lt;%s&gt;</eqconfig>

while currently in tidy-config.xml, the output of tidy -xml-config, only the name of the option is included in <seealso> values:

<seealso>indent</seealso>

Including the initial dash would allow to refer both to command-line options and configuration options in <seealso> values:

<seealso>-indent</seealso>
<seealso>--indent-spaces</seealso>

[geoffmcl]

@eric-brechemier thanks for this issue...

Similar to my comment in #491, why would you want the <seealso> values of -xml-config to be like the <eqconfig> values of -xml-help?

As indicated there, they come from different tables, with different level of information about an option.

While processing the -xml-config, namely the libraries option_defs table, there is a second table docs_xrefs[], which cross references certain config options with some other config options, if present for any option these will be output as <seealso>... Since these are all config type options, then each could be used on the command line with a double dash, or in a config file with a colon, :... Indeed some of them may have a single dash command line option, but we have no such cross-referenced table...

While processing the '-xml-help', namely the tidy.c table, cmdopt_defs, some of these single dash command line options will have a hard coded double dash config options, and these will be shown as <eqconfig>... I do not know why each of these are shown only in the colon form..

So in the first case, <seealso> they are just possibly related things, like if you are interested in say wrap-attributes, then you may also be interested in say wrap-script-literals, or literal-attributes, but these are just hints, guesses, and nothing to do with each other really... and they are all double dash or colon options...

In the second case, <eqconfig>, you are looking at a single dash command line option, and for sure you may also want to know what is the equivalent option you can place in a config file, or use on the command line with a double dash...

Maybe I misunderstand something here... or got something wrong... please explain... thanks...

[eric-brechemier]

@geoffmcl the idea was to allow referring to both kinds of options in <seealso> sections. The suggestion is to use single and double dashes to differentiate command-line options from configuration options.

The general idea between this issue and #491 was to introduce a new convention to refer to command-line options (prefixed by a single dash) and configuration options (prefixed by a double dash), notwithstanding the fact that configuration options can also be used without the double dashes, in configuration files.

[balthisar]

Kind of the same thing as I mentioned in #491 is going on here, too. -xml-config isn't intended solely for console argument use, but for LibTidy users, too, where CLI switches don't even exist.

Maybe it could work with a new key instead of <seealso> (e.g., <console_arg>) so that LibTidy users doing their own transformations can safely ignore these XML elements. However, implementing this isn’t a simple task. Take a look at the docs_xrefs[] structure in message.c, as well as the arrays defined just above it. These are all related to the tidyOptGetDocLinksList() family, which work with known, valid, LibTidy types, and CLI switches aren’t valid types. (If you look in tidy.c, you’ll notice that all of the CLI switches are converted to options during execution.)

To do it the right, “Tidy” way you’d want to define another structure with string values for the CLI switches, and write new iterators and accessors, and finally call them from the console application. I’d welcome a PR, and either @geoffmcl or I could coach you along the way.

[geoffmcl]

@eric-brechemier, @balthisar, now I understand more, am certainly all for for more cross reference help information...

As carefully clarified here and some other related comments, there are two levels of help -

1. Help for the console app user, and give the big list of command line switches - single dash
2. Help for a user's app, that wants to link with, and use libTidy, interested in the config options.

Now the console app also allows the config options to be put in config file, and used on the command line, with a double dash.

The list 1. is built from a table, cmdopt_defs, in the console app code, tidy.c, and it includes a column giving the <eqconfig> option. ie the euivalent config option.

The list 2. is built from a table, option_defs, in the library code, config.c, with iterators and accessors so they can be enumerated by an app. And it includes some maybe related options, from docs_xrefs[], as <seealso>.

But I do not see it correct that another structure be added to the library code, to enumerate CLI switches, only used by the console app, tidy.c. That information has nothing to do with the library.

When doing the -xml-config, output, ie list 2, as suggested, we could add a new key, like say, <console_arg>, or even <eqconsole>...

And the services XMLoptionhelp, ForEachOption, printXMLOption, which, as stated, are enumerating the option_defs, could also lookup the cmdopt_defs, find the <eqconfig> for the current option, and thus add a new key <eqconsole>, giving the equivalent command line switch, or switches, with language translations... simple...

So it seems to me, if we want this cross reference between config options, and its equivalent command line option(s), then all the table information is already there... no need for a new structure anywhere...

In printXMLOption, after say printXMLCrossRef, we could have a new service say printXMLEqConsole, which added this new key... then with a little XSL translation, these <eqconsole> items would appear in the tidy.1 man page...

As stated, would welcome a PR on this, and would help in any way I can... thanks...

[balthisar]

There's nothing currently in cmdopt_defs that relates it to a config option, though. But you're right: a structure can be avoided easily by adding a new field to the CmdOptDesc type and adding the related Tidy option ID to the structure in tidy.c.

[geoffmcl]

@balthisar what about the ctmbstr eqconfig member of the cmdopt_defs table?

Like -output <%s> has output-file: <%s>, etc!

[balthisar]

I guess if @eric-brechemier is motivated enough, that could work.

If we were outputting TidyOutFile, we'd have to get its name (output-file) and then look in every array in cmdops_defs hoping to find a eqconfig starting with output-file+ :, and then we know name1..3 as cross references. Definitely want the colon in the test so you don't match on substrings...

[geoffmcl]

@balthisar not sure why you make it sound difficult...

If we are outputting TidyOutFile, then 'printXMLOption' already has the d->name...

Then a simple case of going though cmdopts_defs using if ((pos->eqconfig) && (strncmp(d->name, pos->eqconfig, strlen(d->name) == 0)), then as you say, your now have pos->name1..3 as cross references...

Of course there are probably a lot of config options that do not have a command line alternative... maybe output as <eqconsole/>, or nothing...

Easy as pie - c'est du gateau in French ;=))

[balthisar]

I thought I did make it sound easy!

"That's the cat's"? Probably gateau's not a cognate of the Spanish gato...

[geoffmcl]

Wow, what would you say if you wanted to make it sound hard? ;=))

A literal translation of the french would be it is of cake, ie C'est tres facile aka easy... nothing to do with Spanish cats ;=))

[eric-brechemier]

I guess if @eric-brechemier is motivated enough, that could work.

:) I don't have much time to dive into C code (my C skills are a bit rusty), but I can make any changes required in the XSLT for the man page, no problem.

[balthisar]

@eric-brechemier, have a look at #510.

If it's okay, I'll merge it and then close this issue.

[balthisar]

Merged, and closed.