diff --git a/README.md b/README.md index 287e9fa701..c94dc0c4c7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ + This repository contains the base source files and tools for converting PHP's documentation, written in DocBook XML, into various presentation -formats like HTML and RTF. +formats. Documentation for the tools used for building the PHP documentation and how to contribute to the documentation and translations can be found in -[the `docs` directory](docs/README.md). +[the `docs` directory](docs/README.md), also hosted at +. If you just want to read the documentation for PHP, look at: https://www.php.net/docs.php diff --git a/configure.php b/configure.php index 49cd55922d..b06cac0dd5 100755 --- a/configure.php +++ b/configure.php @@ -1287,7 +1287,6 @@ function phd_sources() $source_map = array(); $base_dir = "{$ac['rootdir']}/{$ac['LANG_BASE_DIR']}"; $source_langs = array( - array('base', $ac['srcdir'], array('manual.xml', 'funcindex.xml')), array($ac['LANG_BASE_DIR'], $base_dir, find_xml_files($base_dir)), ); if (!is_single_language()) { diff --git a/docs/local-setup.md b/docs/local-setup.md index 103d9add29..435bd46ed3 100644 --- a/docs/local-setup.md +++ b/docs/local-setup.md @@ -48,7 +48,7 @@ instructions](local-web-setup.md) for details on how to view those.) ## Building without make or Docker -## Check out the PHP documentation using Git +### Check out the PHP documentation using Git Note that `doc-en` is cloned into the `en` directory below. @@ -60,7 +60,7 @@ $ git clone https://github.com/php/doc-base.git $ git clone https://github.com/php/doc-en.git en ``` -## Validate and build `.manual.xml` +### Validate and build `manual.xml` ``` $ php doc-base/configure.php @@ -70,7 +70,7 @@ Running `configure.php` will check and validate the XML according to the Docbook specification. It will output either error messages explaining any problems, or an ASCII cat. -This creates the file `doc-base/.manual.xml` which can then be used +This creates the file `doc-base//temp/manual.xml` which can then be used to generate other formats of the documentation. If you are building a translation, you'll also need to specify the @@ -85,33 +85,32 @@ When building a language, you still need to clone both the `doc-en` repository (again, as `en`) so it can be used as the fallback for files that are not yet translated. -## Build other formats of the documentation +### Build other formats of the documentation -`phd` can turn the `doc-base/.manual.xml` generated by `configure.php` +`phd` can turn the `doc-base/temp/manual.xml` generated by `configure.php` into several different formats, including a single HTML file, a multiple-file ("chunked") HTML version, and a special version of the HTML used by the PHP.net website. ```sh -$ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml +$ php phd/render.php --docbook doc-base/temp/manual.xml --package PHP --format xhtml $ open output/php-chunked-xhtml/index.html ``` To build the version for the website (with a [local web setup](local-web-setup.md)): ```sh -$ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php +$ php phd/render.php --docbook doc-base/temp/manual.xml --package PHP --format php $ open https://localhost:8080/manual/en/ ``` -## Translating on Windows +## Working on Windows When working on Windows, try to use text editors that preserve the end -of line mark as `U+000A LINE FEED (LF)` only. If it's not possible, +of line mark as `U+000A LINE FEED (LF)`. If it's not possible, you may issue the commands below to instruct `git` in transforming -the files in your local clone to use the Windows native end of line -mark: +the clone local files to use the Windows native end of line mark: ``` cd LANG @@ -120,8 +119,8 @@ git add --renormalize . git status ``` -If the last comment above outputs no files, then the process works, -and you can start translating. +If the last comment above outputs no files, then the configuration +worked, and you can use the files with the native Windows line end. If the last command above shows a list of files, something went wrong, because these listed files will be changed at *repository level* diff --git a/docs/public-builds.md b/docs/public-builds.md index eeeaec9623..6d7f5c98a2 100644 --- a/docs/public-builds.md +++ b/docs/public-builds.md @@ -4,12 +4,13 @@ The manual and all of its translations is automatically rebuilt and made available at PHP.net through a regular process handled by the systems team. -Currently, this happens every few hours. +Currently, this happens every two hours. If there appear to be problems with the regular building of the manual or -any translation, contact the [PHP Systems team](mailto:systems@php.net) -for help. (The process is automated and monitored, so problems are -generally dealt with promptly.) +any translation, inspect the build logs at or +contact the [PHP Systems team](mailto:systems@php.net) for help. +(The process is automated and monitored, so problems are generally +dealt with promptly.) ## CHM builds diff --git a/entities/global.ent b/entities/global.ent deleted file mode 100644 index 3ca270066a..0000000000 --- a/entities/global.ent +++ /dev/null @@ -1,701 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -superglobals'> -__autoload'> - -Composer'> - -PECL'> - -PIE'> - - - - - -true'> -false'> -null'> - -array'> -int'> -string'> -bool'> -float'> -object'> -resource'> -mixed'> -never'> - - -throw'> -try'> -catch'> -finally'> - - -function'> -return'> - - -namespace'> -use'> - - -const'> -declare'> -foreach'> -global'> -instanceof'> -new'> -yield'> -yield from'> - -intcallbackmixedamixedb'> - -php.ini'> -.user.ini'> -httpd.conf'> -.htaccess'> diff --git a/funcindex.xml b/funcindex.xml deleted file mode 100644 index 4e0fdf51b3..0000000000 --- a/funcindex.xml +++ /dev/null @@ -1,27 +0,0 @@ - - - - - - - &IndexListing; -
- &FunctionListing; - &FunctionListingDescription; - -
-
- &ExampleListing; - &ExampleListingDescription; - -
- diff --git a/manual.xml b/manual.xml deleted file mode 100644 index cae7b040b5..0000000000 --- a/manual.xml +++ /dev/null @@ -1,510 +0,0 @@ - - - - -This file is now being ignored, after third-party manual split. -Yet, it is mentioned by name in configure.php, on PhD related -code paths. - -After these code paths are updated or moved into PhD, this can -be deleted. - -Keep these comments outside SGML comment tags, as to make this -file invalid for XML loading. - - - - - -%configure; - - - -%manual-entities; - - -%translation-defs; -%translation-snippets; -%translation-extensions; - - - - - -%language-defs.default; -%extensions.default; -%language-snippets.default; - - - - - -%global.entities; -%file.entities; -%frontpage.entities; -]> - - - &PHPManual; - &bookinfo; - - - &PHPManual; - &preface; - - - - &GettingStarted; - &chapters.intro; - &chapters.tutorial; - - - - &InstallAndConfigure; - &install.intro; - &install.unix.index; - &install.macos.index; - &install.windows.index; - &install.cloud.index; - &install.fpm.index; - &install.pecl; - &install.composer; - &install.pie; - &install.ini; - - - - &LanguageReference; - &language.basic-syntax; - &language.types; - &language.variables; - &language.constants; - &language.expressions; - &language.operators; - &language.control-structures; - &language.functions; - &language.oop5; - &language.namespaces; - &language.enumerations; - &language.errors; - &language.exceptions; - &language.fibers; - &language.generators; - &language.attributes; - &language.references; - &language.predefined.variables; - &language.predefined.exceptions; - &language.predefined.interfaces; - &language.predefined.attributes; - &language.context; - &language.wrappers; - - - - &Security; - &security.intro; - &security.general; - &security.cgi-bin; - &security.apache; - &security.sessions; - &security.filesystem; - &security.database; - &security.errors; - &security.variables; - &security.hiding; - &security.current; - - - - &Features; - &features.http-auth; - &features.cookies; - &features.sessions; - &features.file-upload; - &features.remote-files; - &features.connection-handling; - &features.persistent-connections; - &features.commandline; - &features.gc; - &features.dtrace; - - - - &FunctionReference; - - - - - - &Seealso; . - - - - - - - - &AffectingPHPsBehaviour; - &reference.apcu.book; - &reference.componere.book; - &reference.errorfunc.book; - &reference.ffi.book; - &reference.opcache.book; - &reference.operator.book; - &reference.outcontrol.book; - &reference.info.book; - &reference.phpdbg.book; - &reference.runkit7.book; - &reference.uopz.book; - &reference.wincache.book; - &reference.xhprof.book; - &reference.yac.book; - - - - &AudioFormatsManipulation; - &reference.openal.book; - - - - &AuthenticationServices; - &reference.radius.book; - - - - &CommandLineSpecificExtensions; - &reference.readline.book; - - - - &CompressionExtensions; - &reference.bzip2.book; - &reference.lzf.book; - &reference.phar.book; - &reference.rar.book; - &reference.zip.book; - &reference.zlib.book; - - - - &CryptographyExtensions; - &reference.hash.book; - &reference.mcrypt.book; - &reference.mhash.book; - &reference.openssl.book; - &reference.password.book; - &reference.rnp.book; - &reference.sodium.book; - &reference.xpass.book; - - - - &DatabaseExtensions; - - - &AbstractionLayers; - &reference.dba.book; - &reference.uodbc.book; - &reference.pdo.book; - - - - &VendorSpecificDatabaseExtensions; - &reference.cubrid.book; - &reference.dbase.book; - &reference.ibase.book; - &reference.ibm-db2.book; - &reference.mongodb.book; - &reference.mysqlinfo.set; - &reference.oci8.book; - &reference.pgsql.book; - &reference.sqlite3.book; - &reference.sqlsrv.book; - - - - - &CalendarandEventRelatedExtensions; - &reference.calendar.book; - &reference.datetime.book; - &reference.hrtime.book; - - - - &FileSystemRelatedExtensions; - &reference.dio.book; - &reference.dir.book; - &reference.fileinfo.book; - &reference.filesystem.book; - &reference.inotify.book; - &reference.xattr.book; - &reference.xdiff.book; - - - - &HumanLanguageandCharacterEncodingSupport; - &reference.enchant.book; - &reference.gender.book; - &reference.gettext.book; - &reference.iconv.book; - &reference.intl.book; - &reference.mbstring.book; - &reference.pspell.book; - &reference.recode.book; - - - - &ImageProcessingandGeneration; - &reference.exif.book; - &reference.image.book; - &reference.gmagick.book; - &reference.imagick.book; - - - - &MailRelatedExtensions; - &reference.imap.book; - &reference.mail.book; - &reference.mailparse.book; - - - - &MathematicalExtensions; - &reference.bc.book; - &reference.gmp.book; - &reference.math.book; - &reference.stats.book; - &reference.trader.book; - - - - &NonTextMIMEOutput; - &reference.fdf.book; - &reference.gnupg.book; - &reference.wkhtmltox.book; - &reference.ps.book; - &reference.rpminfo.book; - &reference.xlswriter.book; - - - - &ProcessControlExtensions; - &reference.eio.book; - &reference.ev.book; - &reference.expect.book; - &reference.pcntl.book; - &reference.posix.book; - &reference.exec.book; - &reference.parallel.book; - &reference.pthreads.book; - &reference.sem.book; - &reference.shmop.book; - &reference.sync.book; - - - - &OtherBasicExtensions; - &reference.geoip.book; - &reference.fann.book; - &reference.igbinary.book; - &reference.json.book; - &reference.simdjson.book; - &reference.lua.book; - &reference.luasandbox.book; - &reference.misc.book; - &reference.random.book; - &reference.seaslog.book; - &reference.spl.book; - &reference.stream.book; - &reference.swoole.book; - &reference.tidy.book; - &reference.tokenizer.book; - &reference.uri.book; - &reference.url.book; - &reference.v8js.book; - &reference.yaml.book; - &reference.yaf.book; - &reference.yaconf.book; - &reference.taint.book; - &reference.ds.book; - &reference.var-representation.book; - - - - &OtherServices; - &reference.curl.book; - &reference.event.book; - &reference.ftp.book; - &reference.gearman.book; - &reference.ldap.book; - &reference.memcache.book; - &reference.memcached.book; - &reference.mqseries.book; - &reference.network.book; - &reference.rrd.book; - &reference.scoutapm.book; - &reference.snmp.book; - &reference.sockets.book; - &reference.ssh2.book; - &reference.stomp.book; - &reference.svm.book; - &reference.svn.book; - &reference.tcpwrap.book; - &reference.varnish.book; - &reference.yaz.book; - &reference.zmq.book; - &reference.zookeeper.book; - - - - &SearchEngineExtensions; - &reference.solr.book; - - - - &ServerSpecificExtensions; - &reference.apache.book; - &reference.litespeed.book; - &reference.fpm.book; - - - - &SessionExtensions; - &reference.session.book; - - - - &TextProcessing; - &reference.cmark.book; - &reference.parle.book; - &reference.pcre.book; - &reference.ssdeep.book; - &reference.strings.book; - - - - &VariableandTypeRelatedExtensions; - &reference.array.book; - &reference.classobj.book; - &reference.ctype.book; - &reference.filter.book; - &reference.funchand.book; - &reference.quickhash.book; - &reference.reflection.book; - &reference.var.book; - - - - &WebServices; - &reference.oauth.book; - &reference.soap.book; - &reference.yar.book; - &reference.xmlrpc.book; - - - - &WindowsOnlyExtensions; - &reference.com.book; - &reference.win32service.book; - - - - &XMLManipulation; - &reference.dom.book; - &reference.libxml.book; - &reference.simplexml.book; - &reference.wddx.book; - &reference.xmldiff.book; - &reference.xml.book; - &reference.xmlreader.book; - &reference.xmlwriter.book; - &reference.xsl.book; - - - - &UIExtensions; - &reference.ui.book; - - - - - &FAQ; - &FAQabbrev; - &faq.general; - &faq.mailinglist; - &faq.obtaining; - &faq.databases; - &faq.installation; - &faq.build; - &faq.using; - &faq.passwords; - &faq.html; - &faq.com; - &faq.misc; - - - - &Appendices; - &appendices.history; - &appendices.examples; - &appendices.migration85; - &appendices.migration84; - &appendices.migration83; - &appendices.migration82; - &appendices.migration81; - &appendices.migration80; - &appendices.migration74; - &appendices.migration73; - &appendices.migration72; - &appendices.migration71; - &appendices.migration70; - &appendices.migration56; - &appendices.debugger; - &appendices.configure.index; - &appendices.ini; - &appendices.extensions; - &appendices.aliases; - &appendices.reserved; - &appendices.resources; - &appendices.filters; - &appendices.transports; - &appendices.comparisons; - &appendices.tokens; - &appendices.userlandnaming; - &appendices.about; - &appendices.license; - &global.function-index; - - &ChangelogListingTitle; - &ChangelogListingBundledDescription; - - - - - - &manual.chmonly; - - - - diff --git a/scripts/file-entities.php b/scripts/file-entities.php index a0b5a47da7..ef26c039f4 100644 --- a/scripts/file-entities.php +++ b/scripts/file-entities.php @@ -26,8 +26,8 @@ The files are created at: -- doc-base/temp/file-entites.ent -- doc-base/temp/file-entites/dir.dir.ent +- doc-base/temp/file-entites.dtd +- doc-base/temp/file-entites/dir.dir.dtd The file entity for directory listings is kept as an separate files, instead of a monolithic one, to avoid these libxml errors, in some @@ -53,27 +53,15 @@ const ENTITY_NAME_REPLACE = true; const LIBXML_LIMITS_HACK = true; -// Setup - -ini_set( 'display_errors' , 1 ); -ini_set( 'display_startup_errors' , 1 ); -error_reporting( E_ALL ); -set_time_limit( 0 ); -ob_implicit_flush(); - -// Usage +// LangDirs are informed in overwriting order: +// Unique/fallback first, optional translation second. $langs = []; $langBase = realpain( __DIR__ . "/../.." ); array_shift( $argv ); foreach( $argv as $arg ) -{ $langs[] = rtrim( $arg , "\\/" ); -} - -// Languages are passed base first, translation second. -// Without arguments, default to the base manual tree. if ( count( $langs ) == 0 ) $langs = [ "en" ]; @@ -97,11 +85,6 @@ exit( 0 ); -// old scheme -// file en -// list en -// file? lang - class Entity { public function __construct( @@ -184,14 +167,6 @@ function check_case_conflict( array $allFIles ) function generate_entities( array $allFiles , array & $entities ) { - // Ugly, but necessary - // TODO move this file from doc-bese to doc-en, with a do-not-translate PI - - $name = 'global.function-index'; - $file = realpain( __DIR__ . "/../funcindex.xml" ); - $text = ""; - pushEntity( $entities , $name , $text ); - // Inclusion of a single file is easy. The entity name is the // relative path without the .xml extension (sadly), and the text // is complete DTD entity with a SYSTEM pointing to the real path @@ -206,18 +181,18 @@ function generate_entities( array $allFiles , array & $entities ) // Inclusion of reference/ directories is a little more involved. // The entity name is calculated from the relative path, but with - // an 'entities' component added in penultimae position. The - // contents are concatened DTD entities references, as above. + // an 'entities' component added in the penultimate position. The + // contents are concatenated DTD entities references, as above. - // LIBXML_LIMITS_HACK - Unfortunatlly, we nedd to put these entities - // that expand in another DTD entities as separate files, to bypass + // LIBXML_LIMITS_HACK - Unfortunately, we need to put these entities + // that expand in other DTD entities as separate files, to bypass // some hardcoded limits of libxml2. This is slow, more so on HDDs. - // BACKPORT_MIXED_REPLACE - Anoying enought, the previous script + // BACKPORT_MIXED_REPLACE - Annoying enough, the previous script // normalized the entity name, but not the file name of the extra file - // file. So indirect file entities ends having a surprising convention: + // file. So indirect file entities end up having a surprising convention: // - // + // // // Mind the distinction between _ and - above. In the future, let's // remove this, to make debugging easier. @@ -232,7 +207,7 @@ function generate_entities( array $allFiles , array & $entities ) if ( ! str_starts_with ( $path , 'reference' ) ) continue; - // Entity name + // DirEnt name // // Discard the file part, 'entities' in the // second-to-last position. @@ -247,18 +222,18 @@ function generate_entities( array $allFiles , array & $entities ) $entName = implode( '.' , $parts ); $entName = str_replace( '_' , '-' , $entName ); // BACKPORT_MIXED_REPLACE - // Entity fila + // DirEnt file // - // dir/dir/dir/file.xml -> dir.dir.dir.ent + // dir/dir/dir/file.xml -> dir.dir.dir.dtd $parts = explode( '/' , $path ); array_pop( $parts ); - array_push( $parts , 'ent'); + array_push( $parts , 'dtd'); $entFile = implode( '.' , $parts ); $groupFilename[ $entName ] = $entFile; - // Contents + // DirEnt item $name = pathToEntityName( $path ); $entRef = "&{$name};"; @@ -290,7 +265,7 @@ function pathToEntityName( string $name , string $removeSuffix = "" ) : string $name = trim( $name , '.' ); return $name; - // ENTITY_NAME_REPLACE, or a TODO to a far future + // ENTITY_NAME_REPLACE, or a TODO to a far future: // - Replace all name replaced entities from doc en // - Add the removed entities on doc-en/entities/remove.ent // - Remove all codepaths related to ENTITY_NAME_REPLACE constant @@ -310,10 +285,10 @@ function pushEntity( array & $entities , string $name , string $text , string $f function writeEntities( array $entities ) { - // Output a single temp/file-entities.ent file for single file inclusion. + // Output a single temp/file-entities.dtd file for single file inclusion. - // Output separate files for file list inclusions, at - // temp/file-entities/dir.dir.dir.ent + // Output separate files for file DirEnt inclusions, at + // temp/file-entities/dir.dir.dir.dtd // LIBXML_LIMITS_HACK ksort( $entities ); @@ -369,11 +344,11 @@ function writeEntities( array $entities ) function writeEntityIndirectSlow( $singleFile , string $extraFile , string $name , string $text ) { - // The entity will point to to a new, individual filename + // The entity will point to to a new, separate filename fputs( $singleFile , "\n" ); - // And the new individual file will hold the final text + // And the new individual file will hold the final file listing file_put_contents( $extraFile , $text ); }