php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #41112 Numbering used for PHP documentation TOC
Submitted: 2007-04-17 07:05 UTC Modified: 2010-12-20 12:25 UTC
Votes:1
Avg. Score:2.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: uttam at hotpop dot com Assigned: bjori (profile)
Status: Wont fix Package: Documentation problem
PHP Version: Irrelevant OS: Irrelavant
Private report: No CVE-ID: None
View Developer Edit
 [2007-04-17 07:05 UTC] uttam at hotpop dot com 
Description:
------------
Hi,

This is regarding the numbering system followed in Table of Contents for PHP English documentation (http://www.php.net/manual/en/).

The are nine top-level sections, numbered using roman numbering as follows:

I. Getting Started
II. Installation and Reference
III. 
.
.
IX. Appendices

The second-level section for the first five sections use contnuous decimal numbering as follows:

I. Getting Started
  1. Introduction
  2. A simple tutorial
II. Installation and Configuration
  3. General Installation Considerations
  4. Installation on Unix systems
  5. Installation on Mac OS X
  6. Installation on Windows systems
  7. Installation of PECL extensions
  8. Problems?
  9. Runtime Configuration
.
.

However, the sub-sections of section V (Function Reference) use roman numbering again:
.
.
VI. Function Reference
  I. .NET Functions
  II. Apache-specific Functions
  III. Alternative PHP Cache
  IV. Advanced PHP debugger
  .
  .
  CLXXXVI. Zip File Functions
  CLXXXVII. Zlib Compression Functions
.
.

From the VII section, the sub-section are again numbered using decimal numbering, with the number continuing from section V:

VII. PHP and Zend Engine Internals
  44. Streams API for PHP Extension Authors
  45. PDO Driver How-To
  .
  .

I can't see the logic behind such numbering. Ideally, the sub-section under each top-level section should use decimal numbering, which starts from 1 under each section, i.e. the numbering should be as follows:

I. Getting Started
  1. Introduction
  2. A simple tutorial

II. Installation and Configuration
  1. General Installation Considerations
  2. Installation on Unix systems
  3. Installation on Mac OS X
  4. Installation on Windows systems
  5. Installation of PECL extensions
  6. Problems?
  7. Runtime Configuration

III. Language Reference
  1. Basic syntax
  2. Types
  3. Variables
  4. Constants
  5. Expressions
  6. Operators
  7. Control Structures
  8. Functions
  9. Classes and Objects (PHP 4)
  10. Classes and Objects (PHP 5)
  11. Exceptions
  12. References Explained
.
.

Also, because of the roman numbering used for the section VI (Function Reference) and the large number of sub-sections, the alignment of the sub-section names w.r.t. left edge keeps varying continuously:

I. .NET Functions
II. Apache-specific Functions
III. Alternative PHP Cache
IV. Advanced PHP debugger
V. Array Functions
VI. Aspell functions [deprecated]
VII. BCMath Arbitrary Precision Mathematics Functions
VIII. PHP bytecode Compiler
IX. Bzip2 Compression Functions
X. Calendar Functions
XI. CCVS API Functions [deprecated]
XII. Class/Object Functions
.
.
CL. SimpleXML functions
CLI. SNMP Functions
CLII. SOAP Functions
CLIII. Socket Functions
CLIV. Standard PHP Library (SPL) Functions
CLV. SQLite Functions
CLVI. SQLite Functions (PDO_SQLITE)
CLVII. Secure Shell2 Functions
CLVIII. Statistics Functions
CLIX. Stream Functions
CLX. String Functions
CLXI. Shockwave Flash Functions
CLXII. Swish Functions
CLXIII. Sybase Functions
CLXIV. TCP Wrappers Functions
CLXV. Tidy Functions
CLXVI. Tokenizer Functions
CLXVII. Unicode Functions
CLXVIII. URL Functions
CLXIX. Variable Handling Functions
CLXX. Verisign Payflow Pro Functions
CLXXI. vpopmail Functions
CLXXII. W32api Functions
CLXXIII. WDDX Functions
CLXXIV. win32ps Functions
CLXXV. win32service Functions
CLXXVI. xattr Functions
CLXXVII. xdiff Functions
CLXXVIII. XML Parser Functions
CLXXIX. XML-RPC Functions
CLXXX. XMLReader functions
CLXXXI. XMLWriter Functions
CLXXXII. XSL functions
CLXXXIII. XSLT Functions
CLXXXIV. YAZ Functions
CLXXXV. YP/NIS Functions
CLXXXVI. Zip File Functions
CLXXXVII. Zlib Compression Functions

For a more logical numbering scheme, I suggest that:
1. All the sub-sections be numbered using decimal numbers.
2. The numbering should restart with change in top-level section.
3. Appendices may retain the current alphabetical numbering.

Thanks & Regards,

Uttam Shukla
India

Expected result:
----------------
I would expect a Table of Contents like this:

I. Getting Started
  1. Introduction
  2. A simple tutorial

II. Installation and Configuration
  1. General Installation Considerations
  2. Installation on Unix systems
  3. Installation on Mac OS X
  4. Installation on Windows systems
  5. Installation of PECL extensions
  6. Problems?
  7. Runtime Configuration

III. Language Reference
  1. Basic syntax
  2. Types
  3. Variables
  4. Constants
  5. Expressions
  6. Operators
  7. Control Structures
  8. Functions
  9. Classes and Objects (PHP 4)
  10. Classes and Objects (PHP 5)
  11. Exceptions
  12. References Explained
.
.
VI. Function Reference
  1. .NET Functions
  2. Apache-specific Functions
  3. Alternative PHP Cache
  4. Advanced PHP debugger
  5. Array Functions
  6. Aspell functions [deprecated]
  7. BCMath Arbitrary Precision Mathematics Functions
  8. PHP bytecode Compiler
  9. Bzip2 Compression Functions
  10. Calendar Functions
  11. CCVS API Functions [deprecated]
  12. Class/Object Functions
  13. Classkit Functions
  14. ClibPDF Functions
  15. COM and .Net (Windows)
  16. Crack Functions
  17. Character Type Functions
  18. CURL, Client URL Library Functions
  19. Cybercash Payment Functions
  20. Credit Mutuel CyberMUT functions
  .
  .
  .
  178. XML Parser Functions
  179. XML-RPC Functions
  180. XMLReader functions
  181. XMLWriter Functions
  182. XSL functions
  183. XSLT Functions
  184. YAZ Functions
  185. YP/NIS Functions
  186. Zip File Functions
  187. Zlib Compression Functions

VII. PHP and Zend Engine Internals
  1. Streams API for PHP Extension Authors
  2. PDO Driver How-To
  3. Zend API: Hacking the Core of PHP
  4. TSRM API
  5. Extending PHP 3

VIII. FAQ: Frequently Asked Questions
  1. General Information
  2. Mailing lists
  3. Obtaining PHP
  4. Database issues
  5. Installation FAQ
  6. Build Problems
  7. Using PHP
  8. PHP and HTML
  9. PHP and COM
  10. PHP and other languages
  11. Migrating from PHP 2 to PHP 3
  12. Migrating from PHP 3 to PHP 4
  13. Migrating from PHP 4 to PHP 5
  14. Miscellaneous Questions

IX. Appendices
  A. History of PHP and related projects
  B. Migrating from PHP 5.1.x to PHP 5.2.x
  C. Migrating from PHP 4 to PHP 5
  D. Migrating from PHP 3 to PHP 4
  E. Migrating from PHP/FI 2 to PHP 3
  F. Debugging PHP
  G. Configure options
  H. php.ini directives
  I. List of Supported Timezones
  J. Extension Categorization
  K. List of Function Aliases
  L. List of Reserved Words
  M. List of Resource Types
  N. List of Supported Protocols/Wrappers
  O. List of Available Filters
  P. List of Supported Socket Transports
  Q. PHP type comparison tables
  R. List of Parser Tokens
  S. Userland Naming Guide
  T. About the manual
  U. Open Publication License
  V. Function Index


Actual result:
--------------
I. Getting Started
1. Introduction
2. A simple tutorial

II. Installation and Configuration
3. General Installation Considerations
4. Installation on Unix systems
5. Installation on Mac OS X
6. Installation on Windows systems
7. Installation of PECL extensions
8. Problems?
9. Runtime Configuration

III. Language Reference
10. Basic syntax
11. Types
12. Variables
13. Constants
14. Expressions
15. Operators
16. Control Structures
17. Functions
18. Classes and Objects (PHP 4)
19. Classes and Objects (PHP 5)
20. Exceptions
21. References Explained

IV. Security
22. Introduction
23. General considerations
24. Installed as CGI binary
25. Installed as an Apache module
26. Filesystem Security
27. Database Security
28. Error Reporting
29. Using Register Globals
30. User Submitted Data
31. Magic Quotes
32. Hiding PHP
33. Keeping Current

V. Features
34. HTTP authentication with PHP
35. Cookies
36. Sessions
37. Dealing with XForms
38. Handling file uploads
39. Using remote files
40. Connection handling
41. Persistent Database Connections
42. Safe Mode
43. Using PHP from the command line

VI. Function Reference
I. .NET Functions
II. Apache-specific Functions
III. Alternative PHP Cache
IV. Advanced PHP debugger
V. Array Functions
VI. Aspell functions [deprecated]
VII. BCMath Arbitrary Precision Mathematics Functions
VIII. PHP bytecode Compiler
IX. Bzip2 Compression Functions
X. Calendar Functions
XI. CCVS API Functions [deprecated]
XII. Class/Object Functions
XIII. Classkit Functions
XIV. ClibPDF Functions
XV. COM and .Net (Windows)
XVI. Crack Functions
XVII. Character Type Functions
XVIII. CURL, Client URL Library Functions
XIX. Cybercash Payment Functions
XX. Credit Mutuel CyberMUT functions
XXI. Cyrus IMAP administration Functions
XXII. Date and Time Functions
XXIII. DB++ Functions
XXIV. Database (dbm-style) Abstraction Layer Functions
XXV. dBase Functions
XXVI. DBM Functions [deprecated]
XXVII. dbx Functions
XXVIII. Direct IO Functions
XXIX. Directory Functions
XXX. DOM Functions
XXXI. DOM XML Functions
XXXII. enchant Functions
XXXIII. Error Handling and Logging Functions
XXXIV. Exif Functions
XXXV. Expect Functions
XXXVI. File Alteration Monitor Functions
XXXVII. Forms Data Format Functions
XXXVIII. Fileinfo Functions
XXXIX. filePro Functions
XL. Filesystem Functions
XLI. Filter Functions
XLII. Firebird/InterBase Functions
XLIII. Firebird/Interbase Functions (PDO_FIREBIRD)
XLIV. FriBiDi Functions
XLV. FrontBase Functions
XLVI. FTP Functions
XLVII. Function Handling Functions
XLVIII. GeoIP Functions
XLIX. Gettext Functions
L. GMP Functions
LI. gnupg Functions
LII. Net_Gopher
LIII. Haru PDF Functions
LIV. hash Functions
LV. HTTP
LVI. Hyperwave Functions
LVII. Hyperwave API Functions
LVIII. IBM Functions (PDO_IBM)
LIX. IBM DB2, Cloudscape and Apache Derby Functions
LX. ICAP Functions [removed]
LXI. iconv Functions
LXII. ID3 Functions
LXIII. IIS Administration Functions
LXIV. Image Functions
LXV. Image magick Functions
LXVI. IMAP, POP3 and NNTP Functions
LXVII. Informix Functions
LXVIII. Informix Functions (PDO_INFORMIX)
LXIX. Ingres II Functions
LXX. IRC Gateway Functions
LXXI. PHP / Java Integration
LXXII. JSON Functions
LXXIII. KADM5
LXXIV. LDAP Functions
LXXV. libxml Functions
LXXVI. Lotus Notes Functions
LXXVII. LZF Functions
LXXVIII. Mail Functions
LXXIX. Mailparse Functions
LXXX. Mathematical Functions
LXXXI. MaxDB PHP Extension
LXXXII. MCAL Functions
LXXXIII. Mcrypt Encryption Functions
LXXXIV. MCVE (Monetra) Payment Functions
LXXXV. Memcache Functions
LXXXVI. Mhash Functions
LXXXVII. Mimetype Functions
LXXXVIII. Ming functions for Flash
LXXXIX. Miscellaneous Functions
XC. mnoGoSearch Functions
XCI. Microsoft SQL Server Functions
XCII. Microsoft SQL Server and Sybase Functions (PDO_DBLIB)
XCIII. Mohawk Software Session Handler Functions
XCIV. mSQL Functions
XCV. Multibyte String Functions
XCVI. muscat Functions
XCVII. MySQL Functions
XCVIII. MySQL Functions (PDO_MYSQL)
XCIX. MySQL Improved Extension
C. Ncurses Terminal Screen Control Functions
CI. Network Functions
CII. Newt Functions
CIII. NSAPI-specific Functions
CIV. Object Aggregation/Composition Functions
CV. Object property and method call overloading
CVI. Oracle Functions
CVII. ODBC Functions (Unified)
CVIII. ODBC and DB2 Functions (PDO_ODBC)
CIX. oggvorbis
CX. OpenAL Audio Bindings
CXI. OpenSSL Functions
CXII. Oracle Functions [deprecated]
CXIII. Oracle Functions (PDO_OCI)
CXIV. Output Control Functions
CXV. Ovrimos SQL Functions
CXVI. Paradox File Access
CXVII. Parsekit Functions
CXVIII. Process Control Functions
CXIX. Regular Expression Functions (Perl-Compatible)
CXX. PDF Functions
CXXI. PDO Functions
CXXII. Phar archive stream and classes
CXXIII. PHP Options&Information
CXXIV. POSIX Functions
CXXV. Regular Expression Functions (POSIX Extended)
CXXVI. PostgreSQL Functions
CXXVII. PostgreSQL Functions (PDO_PGSQL)
CXXVIII. Printer Functions
CXXIX. Program Execution Functions
CXXX. PostScript document creation
CXXXI. Pspell Functions
CXXXII. qtdom Functions
CXXXIII. Radius
CXXXIV. Rar Functions
CXXXV. GNU Readline
CXXXVI. GNU Recode Functions
CXXXVII. RPM Header Reading Functions
CXXXVIII. runkit Functions
CXXXIX. SAM - Simple Asynchronous Messaging
CXL. Satellite CORBA client extension [deprecated]
CXLI. SCA Functions
CXLII. SDO Functions
CXLIII. SDO XML Data Access Service Functions
CXLIV. SDO Relational Data Access Service Functions
CXLV. Semaphore, Shared Memory and IPC Functions
CXLVI. SESAM Database Functions
CXLVII. PostgreSQL Session Save Handler
CXLVIII. Session Handling Functions
CXLIX. Shared Memory Functions
CL. SimpleXML functions
CLI. SNMP Functions
CLII. SOAP Functions
CLIII. Socket Functions
CLIV. Standard PHP Library (SPL) Functions
CLV. SQLite Functions
CLVI. SQLite Functions (PDO_SQLITE)
CLVII. Secure Shell2 Functions
CLVIII. Statistics Functions
CLIX. Stream Functions
CLX. String Functions
CLXI. Shockwave Flash Functions
CLXII. Swish Functions
CLXIII. Sybase Functions
CLXIV. TCP Wrappers Functions
CLXV. Tidy Functions
CLXVI. Tokenizer Functions
CLXVII. Unicode Functions
CLXVIII. URL Functions
CLXIX. Variable Handling Functions
CLXX. Verisign Payflow Pro Functions
CLXXI. vpopmail Functions
CLXXII. W32api Functions
CLXXIII. WDDX Functions
CLXXIV. win32ps Functions
CLXXV. win32service Functions
CLXXVI. xattr Functions
CLXXVII. xdiff Functions
CLXXVIII. XML Parser Functions
CLXXIX. XML-RPC Functions
CLXXX. XMLReader functions
CLXXXI. XMLWriter Functions
CLXXXII. XSL functions
CLXXXIII. XSLT Functions
CLXXXIV. YAZ Functions
CLXXXV. YP/NIS Functions
CLXXXVI. Zip File Functions
CLXXXVII. Zlib Compression Functions

VII. PHP and Zend Engine Internals
44. Streams API for PHP Extension Authors
45. PDO Driver How-To
46. Zend API: Hacking the Core of PHP
47. TSRM API
48. Extending PHP 3

VIII. FAQ: Frequently Asked Questions
49. General Information
50. Mailing lists
51. Obtaining PHP
52. Database issues
53. Installation FAQ
54. Build Problems
55. Using PHP
56. PHP and HTML
57. PHP and COM
58. PHP and other languages
59. Migrating from PHP 2 to PHP 3
60. Migrating from PHP 3 to PHP 4
61. Migrating from PHP 4 to PHP 5
62. Miscellaneous Questions

IX. Appendices
A. History of PHP and related projects
B. Migrating from PHP 5.1.x to PHP 5.2.x
C. Migrating from PHP 4 to PHP 5
D. Migrating from PHP 3 to PHP 4
E. Migrating from PHP/FI 2 to PHP 3
F. Debugging PHP
G. Configure options
H. php.ini directives
I. List of Supported Timezones
J. Extension Categorization
K. List of Function Aliases
L. List of Reserved Words
M. List of Resource Types
N. List of Supported Protocols/Wrappers
O. List of Available Filters
P. List of Supported Socket Transports
Q. PHP type comparison tables
R. List of Parser Tokens
S. Userland Naming Guide
T. About the manual
U. Open Publication License
V. Function Index

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2007-04-17 07:28 UTC] bjori@php.net 
You have a good point there.
I'll look into it
 [2007-10-05 06:23 UTC] ath at algonet dot se 
The most serious problem, in my opinion, is that of roman numerals being used in one section. 

The way the subsections are numbered (consecutively through the sections) is a problem of a different kind: adding a subsection in section one will throw all subsequent subsections off by one, and so cause problems in references by section number alone.
 [2007-10-06 10:33 UTC] bjori@php.net 
I really dislike numbering chapter, references, tutorials...
I really don't see the point, as "ath" mentioned whenever a new chapter/reference/whatever is added the numbers change.

Referring to a chapter by its number doesn't make sense for us and have therefore been been removed in phd (the new build system), see: http://docs.php.net/manual/en/index.php

I have no intentions of adding them back unless someone can come up with a real argument for keeping them.

(On a related note: Examples are no longer numbered absolutely. See http://docs.php.net/manual/en/ref.pdo.php)

-Hannes
 [2010-12-20 12:25 UTC] jani@php.net
-Package: Tidy +Package: Documentation problem
 
PHP Copyright © 2001-2025 The PHP Group
All rights reserved. 		Last updated: Thu Mar 13 19:01:31 2025 UTC