redhat-developer / redhat-developer/vscode-xml

Validator cannot find references in external files (xinclude)

Open
#835 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
328
Forks
101
Avg merge
1d 17h
Merged PRs (30d)
7

Description

We have modular docbook documentation where there are cross-references between elements that are in different files.
It would be great if the plugin could resolve these references and not show a validation error. As I understand this problem has two levels.
One is where the reference (id-in-child) is pointing from parent (File_A) to a child (File_B) file, probably the easier one to solve.
File_A:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                      "http://www.docbook.org/xml/4.4/docbookx.dtd"      
[ <!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod"> %xinclude; ]>

<book>

<chapter>
<title>Content of File A</title>
<para><xref linkend="id-in-child">Xref to section in child</xref></para>
</chapter>

<xi:include href="File_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

</book>

File_B:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                      "http://www.docbook.org/xml/4.4/docbookx.dtd" 
[ <!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod"> %xinclude; ]>

<chapter>
    <title>Contents of File B</title>
<section  id="id-in-child">
    <title></title>
    <para></para>
</section>
</chapter>

In this case, the validator could look inside the included File_B to see if the referred ID is inside (as it is already validating File_B as part of its own validation).

The second case is where either the child refers to something in the parent, or a child refers to an element in another child.
In this case, the validation process must somehow understand what are parent files and what are all the files that are relevant for the validation. That would allow it to look at all parent files of a child file to see if the reference in the child points to something directly in the parent file, or to something in one of the other children files of the parent. Oxygen Editor/Author does this by allowing users to define all files that are in a "project" and appoint "master files" through which all references between children can be resolved). It would be great to have something like this here too.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the DocBook File_A and File_B examples with XInclude and inspect the validator's current handling of cross-file references. Define completion as resolving references from a parent to an included child, from a child to its parent, and between sibling children without validation errors, including project or master-file scope where needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, xml
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.