8000 BC Break between DocBook 5.1 and DocBook 5.2 · Issue #262 · docbook/docbook · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

BC Break between DocBook 5.1 and DocBook 5.2 #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Girgias opened this issue Oct 14, 2024 · 4 comments
Open

BC Break between DocBook 5.1 and DocBook 5.2 #262

Girgias opened this issue Oct 14, 2024 · 4 comments

Comments

@Girgias
Copy link
Girgias commented Oct 14, 2024

I am well aware that this is not the mailing list nor the correct channel, but every single link on the OASIS website is just broken, and has been broken since April when I first started to bring this issue to the attention of the committee.

As such, I hope that publishing the issue here will allow someone that might be more familiar with the process to contact the relevant people or indicate me what I need to do. I emailed Robert Stayton back in April, and have had no reply.
The email is as following:

I work on the PHP programming language, and the documentation is written in XML and currently follows DocBook with some slight tweaks (it is based on a DocBook 4.x DTD but follows some DocBook 5.2 for the <type> tag).
I am attempting to drop our custom schema to use DocBook 5.2, however I have encountered what I believe is either a bug or an undocumented backwards incompatibility change between DocBook 5.1 and DocBook 5.2.

The issue is about the schema of the <classsynopsis> tag.
According to DocBook 5.1 (https://tdg.docbook.org/tdg/5.1/classsynopsis) the tag is composed of:
    Sequence of:
        ********One or more of:********
            Object-oriented programming inlines [-]
                ooclass
                ooexception
                oointerface
        Zero or more of:
            classsynopsisinfo
            constructorsynopsis
            destructorsynopsis
            fieldsynopsis
            methodsynopsis


And in DocBook 5.2 (https://tdg.docbook.org/tdg/5.2/classsynopsis) the tag is composed of:
    Sequence of:
        info? ([db.titleforbidden.info](http://db.titleforbidden.info/))
        Zero or more of:
            classsynopsisinfo
        Zero or more of:
            templatename
        ********One of:********
            ooclass
            ooexception
            oointerface
        Zero or more of:
            classsynopsisinfo
            constructorsynopsis
            destructorsynopsis
            fieldsynopsis
            methodsynopsis
            ooexception
            template

Please note the emphasis I've added via the use of ********.

In DocBook 5.1, 5.0, and 4.5 one could always have _multiple_ ooclass/ooexception/oointerface tags within a classsynopsis tag.
However, in DocBook 5.2 one is only permitted a _single_ one of those tags.

This is an issue for the PHP Documentation project, as we use individual oointerface tags to indicate what interfaces a class implements, and an extra ooclass tag to indicate from what parent class this class extends.
For a relative complete example see: https://github.com/php/doc-en/blob/master/reference/spl/cachingiterator.xml

Could you indicate to me if this is an issue with the newly released DocBook 5.2 spec, or if we need to determine new XML markup for our purpose?

In the meantime, I have updated our XML source and schema to be DocBook 5.2 with an amendment to the RelaxNG schema relaxing the constraint for <classsynopsis> (see: php/doc-base#123)

In the hope that this issue will be addressed upstream at one point.
@ndw
Copy link
Contributor
ndw commented Oct 16, 2024

(I know about the mailing list issues; I have some sympathy for the position OASIS is in, but I'm also hoping to setup new lists "real soon now".)

I think you're right that's a backwards incompatible change. We wouldn't have done that in 5.2 if we'd noticed. I'll make sure whatever comes next fixes that.

(I'd be curious to see an example of the your markup that is no longer valid.)

@Girgias
Copy link
Author
Girgias commented Oct 16, 2024

Thank you for the swift reply :)

One of the XML files that doesn't conform any more is: https://github.com/php/doc-en/blob/master/reference/spl/cachingiterator.xml (ignore the magic XML entities that exist and are subsections of the class)

@ndw ndw transferred this issue from docbook/defguide Oct 16, 2024
@ndw
Copy link
Contributor
ndw commented Oct 16, 2024

(I moved this issue to the docbook repo, btw.)

I don't see any examples in our test suite for a classsynopsis that demonstrates markup for extends or implements. And I can't see how you'd do it. I'm not even sure I like the options in DocBook 5.1.

@Girgias
Copy link
Author
Girgias commented Oct 16, 2024

I agree, the current options are not great.

Previously, we would shove all the information into a <classsynopsisinfo> tag, however this caused issues on our side with rendering interface definitions that extended multiple other interfaces.

I then decided to redo the markup for classes and interfaces to use <ooclass> and <oointerface> with the corresponding <modifier> tag for the first of such element if it extends/implements a class/interfaces.

Which would look like this:

<classsynopsis class="class">
 <ooclass>
  <classname>ChildClass</classname>
 </ooclass>

 <ooclass>
  <modifier>extends</modifier>
  <classname>ParentClass</classname>
 </ooclass>

 <oointerface>
  <modifier>implements</modifier>
  <interfacename>Interface1</interfacename>
 </oointerface>

 <oointerface>
  <interfacename>Interface2</interfacename>
 </oointerface>

 <oointerface>
  <interfacename>Interface3</interfacename>
 </oointerface>

  <classsynopsisinfo role="comment">Constants</classsynopsisinfo>
  <fieldsynopsis>
   <modifier>public</modifier>
   <modifier>const</modifier>
   <type>int</type>
   <varname>ChildClass::CONSTANT_NAME</varname>
  </fieldsynopsis>
  <!-- etc. -->
</classsynopsis>

One idea to have "better" markup would be to allow nesting <ooclass>/<oointerface>/<ooexception> inside of one of these tags to create a hierarchy.

e.g.

<ooclass>
 <classname>ChildClass</classname>

 <ooclass>
  <classname>ParentClass</classname>
 </ooclass>

 <oointerface>
  <interfacename>Interface1</interfacename>
 </oointerface>

 <oointerface>
  <interfacename>Interface2</interfacename>
 </oointerface>

 <oointerface>
  <interfacename>Interface3</interfacename>
 </oointerface>
</ooclass>

And it would then be the job of the renderer to take this markup and transform this into:

class ChildClass extends ParentClass implements Interface1, Interface2, Interface3
{
    /* Fill in body of class */
}

Now, PHP specific problem, is that our enums are basically classes, meaning they can also have associated methods, which the <enumsynopsis> tag doesn't allow. So we might need to be a bit creative, but that's a completely separate issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@ndw @Girgias
0