Schema documentation questions

[Christian Roth]

Hello,

I'm currently documenting a schema by attaching documentation annotations to elements and attributes. For some of the documentation, I want to refer to other element or attribute definitions by hyperlinking.

However, I am unsure how to determine the link target so that e.g. in generated HTML documentation output, the links point to the respective element's documentation. It seems that the link targets are not "speaking", but just numbered names like "id1", "id2" etc. which may obviously change on each run of the documentation generator or when the schema is otherwise edited. Is there a way to reliably link to certain element or attribute documentation in the final output by using speaking, unambiguous target names, like e.g. it is implemented in javadoc? I already tried setting @id on the respective xs:element elements (i.e., manually and explicitly assign IDs to the elements I want to hyperlink to), but those values do not seem to get used during schema documentation generation.

Any tips on how I should go about that?

Thanks, Christian

[alex_jitianu]

Hello,

Indeed, there are 2 problems.

First, the ids used to identify the components are generated using a counter.

Second, if you are using a split method (by namespace, location or component), the name of the html files are generated using the name of the given output file + another counter.

Basically if the schema structure doesn't change, the counters will have the same values so the same ids/file names will be generated.

I've added a bug on our internal bug tracking system and we intend to solve these two problems as follows:
- the id for a component will be the value of the 'id' attribute of that component, if it exists. If not, the current mechanism will be used.

- if a split method will be used, the name of the output file will be :
a. for split by namespace, the output file name will be the namespace (characters that are not permitted in file names will be escaped)
b. for split by location, the output file name will be the name of the schema
c. for split by component, the output file name will be the name of the global component that appears in that file.

Please let me know if you have additional suggestions.

Best regards,
Alex

[alex_jitianu]

Hello,

Will it be helpful if we also add support for handling a 'seeAlso' element in appInfo? You will have to specify the namespace, local name and component type and we will automatically replace it in the documentation with a link to the actual location of that component.

Best regards,
Alex

[Christian Roth]

(Sorry for the late reply - I thought I had subscribed to the thread, but did not get email notifications on your answers.)

Ah - I did not think of the split modes. But your solution sounds fine, although I will have to take the (later used) split mode into account when constructing the URLs in my inline links.

Regarding <seeAlso>: I don't think this would help in my case, as I would like to place the links inline in xs:documentation. I am not using appInfo right now. Is this a mis-use on my part of the documentation elements?

Is the solution you suggested already part of the latest update to oXygen?

Thanks, Christian

[alex_jitianu]

Hello,

The <seeAlso> tags is just an idea we thought about (not yet implemented). The benefits are that we could automatically generate the links depending on the predefined output format (html, docbook, pdf). But unfortunately they wont appear inline in documentation, just before or after it.

Best regards,
Alex

[sorin_ristache]

Hello Christian,

I've added a bug on our internal bug tracking system and we intend to solve these two problems as follows:
- the id for a component will be the value of the 'id' attribute of that component, if it exists. If not, the current mechanism will be used.

- if a split method will be used, the name of the output file will be :
a. for split by namespace, the output file name will be the namespace (characters that are not permitted in file names will be escaped)
b. for split by location, the output file name will be the name of the schema
c. for split by component, the output file name will be the name of the global component that appears in that file.

Ah - I did not think of the split modes. But your solution sounds fine, although I will have to take the (later used) split mode into account when constructing the URLs in my inline links.

We implemented this naming scheme and it will be available starting with Oxygen version 12.2 which we will release in less than a month (probably in about two weeks).


Regards,
Sorin