Fix and rewrite DocBook chapter for standards compliance and clarity.

[Nikhilanandd]

Pull Request: Rewrite and Correct DocBook Chapter for Standards Compliance

Summary

This pull request rewrites the entire DocBook chapter to ensure full compliance with DocBook 5.x standards, improve readability, correct structural issues, and enhance documentation quality. The original file contained several formatting inconsistencies, deprecated elements, and structural errors that could affect parsing, rendering, and long-term maintainability.

Key Improvements

1. Structural Corrections

• Reordered <title> and <titleabbrev> to follow proper DocBook metadata hierarchy.
• Moved <example> elements outside <para> blocks as required by DocBook.
• Replaced deprecated <simpara> elements with <para>.
• Ensured consistent indentation, nesting, and XML structure.

2. Code Block and CDATA Fixes

• Reformatted the PHP example inside <![CDATA[]]> for clarity.
• Removed unnecessary indentation and spacing inconsistencies.

3. Language, Clarity, and Formatting Enhancements

• Improved grammar, clarity, and tone across all paragraphs.
• Removed informal or ambiguous expressions.
• Revised explanations while preserving original meaning.

4. Standards and Conventions Alignment

• Ensured link elements follow proper DocBook reference patterns.
• Removed undefined or non-portable entity references.
• Adjusted element order and formatting based on DocBook 5.x guidelines.

5. Overall Quality Improvements

• Improved documentation flow and readability.
• Enhanced consistency and maintainability.
• Ensured the chapter is valid and well-formed XML suitable for transformation.

Why These Changes Matter

These updates improve:

• Compatibility with DocBook processing tools
• Long-term maintainability of documentation
• Clarity and technical accuracy
• Consistency across the documentation set

Files Updated

• introduction.xml — complete rewrite for accuracy, correctness, and consistency.

Ready for Review

The revised chapter complies with DocBook standards and is ready for integration. Feedback or further refinements are welcome.

[Nikhilanandd]

Pull Request: Fix and Clean Up Tutorial DocBook Chapter

Summary

This pull request updates the tutorial DocBook chapter to correct structural issues, remove custom entity dependencies, and improve overall clarity and standards compliance. The original XML relied on manual-specific entities (such as &url.*; and &true;/&false;), used simpara in several places, and wrapped block-level <example> elements inside <para> elements, which is not ideal for DocBook processors.

The updated file is self-contained, structurally correct, and better aligned with DocBook 5 best practices.

---

Key Changes

1. Structural and Element-Level Fixes

• Replaced all <simpara> elements with <para> for consistency and compatibility.
• Moved <example> elements out of wrapping <para> blocks so they appear as proper block-level siblings.
• Ensured valid block structure inside <example> elements (<programlisting>, <screen>, <para>, etc.).

2. Entity Replacement and Link Updates

• Replaced manual-specific URL entities:

  • &url.php.downloads; → https://www.php.net/downloads.php
  • &url.phpeditorlist; → https://www.php.net/sites.php
  • &url.php.talks; → http://talks.php.net/

• Removed boolean entities &true; and &false; and replaced them with literal values wrapped in <literal> where appropriate.

3. Content and Clarity Improvements

• Clarified the explanation of str_contains() to describe its true/false return values explicitly.
• Slightly tightened wording around user agent examples and the explanation of how conditional blocks are executed.
• Kept the original meaning and flow of the PHP tutorial content while making it cleaner and more consistent.

4. Code Example and CDATA Formatting

• Normalized indentation inside <![CDATA[ ... ]]> blocks for PHP, shell, HTML, and output examples.
• Ensured examples are readable and ready for transformation into other formats (HTML, PDF, etc.).

---

Why This Change Is Useful

• Improves compatibility with generic DocBook toolchains that do not have the PHP manual’s custom DTD/entities.
• Makes the chapter easier to maintain and extend.
• Reduces the chance of validation errors or processing failures in downstream tools.
• Keeps the content aligned with current official URLs for downloads and conference materials.

---

Files Updated

• tutorial.xml (rewritten and cleaned for structure, entities, and clarity)

---

Notes

• The semantics and examples closely follow the current PHP manual, but the XML is now more self-contained and DocBook-5-friendly.
• If desired, follow-up changes can add schema validation to CI to ensure future edits remain compliant.