php / php/phd

Can <subtitle> not be used?

Open
#258 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
91
Forks
59
PR merge metrics
No merged PRs in 30d

Description

I am wanting to update the (as yet unpublished) operator docbook. I was updating the the installation page to include the following:

[...]
  <section>
   <title>PECL</title>
   <subtitle>Deprecated</subtitle>
[...]

When I built the docs locally I got the following warning:

[18:13:24 - E_USER_WARNING        ] /raid/projects/ext/github.com/jb-lopez/phpdoc/phd/phpdotnet/phd/Format/Abstract/XHTML.php:45
        No mapper found for 'subtitle'

And the output is as unformatted text. The MWE I got to both build and produce the warning was this:

<?xml version="1.0" encoding="utf-8"?>
<chapter>
 <title>test</title>
 <subtitle>test</subtitle>
</chapter>

I tried with different parent elements not just chapter, but also section, simplesect, and sect1. It just seems that subtitle it not mapped? I can see it here but I haven't grokked this code so I don't know what is looking at this to know how things map.

I also grep'd through the doc-en and doc-base, and it seems like no one is using the <subtitle> tag. Should I avoid it as well?

Contributor guide

No contributing guide indexed for this repository

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 warning with the minimal chapter XML and local documentation build, then inspect phpdotnet/phd/Format/Abstract/XHTML.php at line 45 and the subtitle mapping referenced in phpdotnet/phd/Package/PEAR/XHTML.php around line 187. Compare the result with existing usage in doc-en and doc-base; done means subtitle behavior is either correctly rendered or its unsupported status is clearly established and documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.