php / doc-base Goto Github PK

View Code? Open in Web Editor NEW

341.0 341.0 82.0 10.46 MB

Tools for the PHP documentation

License: Other

HTML 0.40% Batchfile 0.53% PHP 82.58% CSS 4.21% Shell 0.68% JavaScript 7.60% Clean 1.21% Smarty 2.80%

doc-base's People

Contributors

Stargazers

Watchers

Forkers

sobak tzubiri cmb69 timoschinkel girgias kocsismate heiglandreas tiffany-taylor mumumu tubbz-alt connectionmaster cwuensche mauriciofauth localheinz whoami15 magicianred micaelparadox wenz zavodilo sveneld adielcristo tysonandre global-localhost global19 global19-atlassian-net thinkverse vorgeryan yeboahnanaosei saundefined asbiin shaedrich lufei salathe deleugpn fulldecent classicvalues nilgun hypemc summercms wenhsing mrvincelee mglaman njames zonuexe stkeke maxamedkhaliif schwarz84 seldaek eugene-augier mallardduck brijeshk89 kamil-tekiela zsq0053 armbiant hugocobos athos-ribeiro antonsviridenko mowangjuanzi timwolla mrailton rhertogh jbafford danack phansys samkenxstream rsiralla alfsb alexandre-daubois ethicalsecurity-agency jean-beru nielsdos batmaxou mmalferov pomelchenko haszi emover121 usergamer0909 cjbj malik1u jimwins hernanitop15172 robertsilen

doc-base's Issues

`pt_BR` failing with outdated data

Hi,

After php/doc-pt_br@e3aa4d7, the pt_BR manual does not build, with error:

The document didn't validate, here are the errors I got:
(If this isn't enough information, try again with --enable-xml-details)
 Element reference content does not follow the DTD, expecting (((title |
 titleabbrev | subtitle)* , info?) , partintro? , refentry+), got (title
 partintro phpdoc:varentry phpdoc:varentry phpdoc:varentry phpdoc:varentry
 phpdoc:varentry phpdoc:varentry phpdoc:varentry phpdoc:varentry phpdoc:varentry
 phpdoc:varentry phpdoc:varentry phpdoc:varentry phpdoc:varentry phpdoc:varentry

I cannot find any varentry usage outside of DTD definitions. Also, the manual builds locally. I think there is some outdated repository on machine building that is causing this.

I also opened #104 , that may facilitate debug this and future cases. It may be complemented with PHD paths that build machine uses.

Wrong link

From manual page: https://php.net/context.ssl

security_level description contains link which redirects to 404 page.

Documenting/improving ways to quickly check docbook xml syntax/correctness on editor save

Motivation

Rendering a part of the docbook takes around 10 seconds for me, even for a partial build, and requires prerequisite steps

time phd --docbook doc-base/.manual.xml --package PHP --partial en/reference/simdjson --format xhtml

Some editors (e.g. vim) don't have xml validation built in, and rely on plugins using external programs such as xmllint (from libxml2-utils) to work, so documenting ways to set up xml validation would save time

Related to php/doc-en#1148

Feature Request

Add example scripts and editorconfigs to quickly check validity of individual xml files to doc-base/scripts.

This could possibly be extended by hardcoding known entities and warning about unknown entities, xml tag names, etc
(or by actually configuring the proper dtd files when run in the doc-base folder)

(other alternatives exist, but usually require external programs, e.g. https://github.com/vim-syntastic/syntastic/blob/master/syntax_checkers/xml/xmllint.vim - assume php documentation contributors would have php installed)

" Example additions to vimrc to check xml tags match up
function! XMLsynCHK()
  let winnum =winnr() " get current window number
  silent make %
  cw 4 " open the error window if it contains error
  " return to the window with cursor set on the line of the first error (if any)
  execute winnum . "wincmd w"
  :redraw!
endfunction
au! BufWritePost  *.xml    call XMLsynCHK()

au FileType xml,docbk setlocal makeprg=/path/to/doc-base/scripts/xmllint.php
au FileType xml,docbk setlocal errorformat=%m\ in\ %f\ on\ line\ %l

#!/usr/bin/env php
<?php // xmllint.php

/** @return never */
function print_usage_and_exit() {
    global $argv;
    fprintf(STDERR, "Usage: %s path/to/file.xml\n", $argv[0]);
    exit(1);
}

call_user_func(function () {
    error_reporting(E_ALL);
    ini_set('display_errors', E_ALL);
    global $argv;
    if (count($argv) !== 2) {
        print_usage_and_exit();
    }
    $file = $argv[1];
    if (!is_readable($file)) {
        fprintf(STDERR, "%s is not readable\n", var_export($file, true));
        print_usage_and_exit();
    }
    $contents = file_get_contents($file);
    if (!is_string($contents)) {
        fprintf(STDERR, "Could not read %s\n", var_export($file, true));
        print_usage_and_exit();
    }
    libxml_use_internal_errors(true);
    try {
        (new DOMDocument())->loadXML($contents, LIBXML_PARSEHUGE|LIBXML_COMPACT);
    } catch (Exception $e) { }
    foreach (libxml_get_errors() as $error) {
        $message = trim($error->message);
        if (preg_match('/^Entity.*not defined$/', $message)) {
            continue;
        }
        
        printf("%s in %s on line %d\n", $message, $file, $error->line);
    }
});

Brainstorming other ideas

For DOMDocument::schemaValidate - I see https://docbook.org/ns/docbook has no official schema. doc-base has RFC/schema for a proposed schema but the commit from 2010 notes "PhD doesn't use any of this"
I'm not familiar with the implementation of the tools. Currently, it seems like we have to generate the entire .manual.xml with the manual of all settings, to generate the html even for one page. (process on http:// site for http://doc.php.net/tutorial/local-setup.php )
I haven't yet looked into whether phd or configure.php can be changed to run on an error-tolerant way on a single file without building the full manual.xml file with every single page (or by using some other method faster for decoding and retrieval than parsing an entire xml file, e.g. putting all the definitions once in sqlite, caching it, and only querying the necessary rows later and on manual request)

Regarding php script licenses

Hello,

While browsing through the code in this repository, I realized that the following files are licensed under PHP-3.0:

configure.php
scripts/file-entities.php.in
scripts/test_missing-entities.php.in
scripts/missing-entities.php.in
scripts/check-trans-params.php
scripts/docgen/docgen.php
scripts/spell-checker.php
scripts/genPHP_INI_ENTRY.php
scripts/xml-check.php
scripts/check-trans.php
scripts/qa/entity-usage.php
scripts/qa/section-order.php
scripts/qa/check-acronyms.php
scripts/qa/checkent.php
scripts/qa/entities.php
scripts/qa/extensions.xml.php
scripts/qa/check-valid-function.php
scripts/dbtags.php
scripts/process.php
scripts/check-trans-maint.php
scripts/versions.php
scripts/notes_stats.php
scripts/revcheck.php
scripts/include/FileData.class.php
scripts/include/lib-translations.inc.php
scripts/orphan_notes.php
scripts/notes_extract.php
scripts/check_phpdoc/view_check_phpdoc.php
scripts/check_phpdoc/build.php
scripts/aspell.php

Would it be possible to re-license those as PHP-3.01 to make it easier to re-distribute the documentation? What sort of effort would it take to do so (e.g., contacting authors, filing PRs, etc)?

Unmarked outdated files

In the PR 132, I mentioned that some 40 files are outdated in all translations, but not marked as so by the doc-base's revcheck.php.

The hashes and filenames below lists the cases I found while developing the PR above. To update your translations, manually inspect the diff of these commit's hashes, or run the PR's version of revchech.php to generate individual file diff links.

After updating the texts, you may leave the hashes unmodified, so these outdated hashes interact correctly with current versions of revchech.php both in doc-base and in web-php.

99,102c99,102
< 26e26a95fdc3aac9b464068953ea3105dee00f14 1 language/predefined/interfaces.xml
< 26e26a95fdc3aac9b464068953ea3105dee00f14 1 language/predefined/php-incomplete-class.xml
< 26e26a95fdc3aac9b464068953ea3105dee00f14 1 reference/igbinary/functions/igbinary-unserialize.xml
< 26e26a95fdc3aac9b464068953ea3105dee00f14 1 reference/var/functions/unserialize.xml
---
> 26e26a95fdc3aac9b464068953ea3105dee00f14  language/predefined/interfaces.xml
> 26e26a95fdc3aac9b464068953ea3105dee00f14  language/predefined/php-incomplete-class.xml
> 26e26a95fdc3aac9b464068953ea3105dee00f14  reference/igbinary/functions/igbinary-unserialize.xml
> 26e26a95fdc3aac9b464068953ea3105dee00f14  reference/var/functions/unserialize.xml
1216c1216
< 8f6fd5c55ab10709a4ff8daf6140dea422c1363c 1 reference/libxml/constants.xml
---
> 8f6fd5c55ab10709a4ff8daf6140dea422c1363c  reference/libxml/constants.xml
1419,1446c1419,1446
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 appendices/filters.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 install/fpm/configuration.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/cubrid/cubridmysql/cubrid-real-escape-string.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/eio/functions/eio-chmod.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/eio/functions/eio-poll.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/ev/depth.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/ev/run.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evchild/construct.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evloop/run.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evstat/attr.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evstat/createstopped.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evstat/set.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evtimer/construct.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evtimer/createstopped.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evtimer/set.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/ev/evwatcher/clear.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/event/eventbufferevent/construct.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/event/eventbufferevent/setwatermark.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/event/eventconfig/setmaxdispatchinterval.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/event/eventdnsbase/parseresolvconf.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/event/eventdnsbase/setsearchndots.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/filesystem/functions/stat.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/imagick/imagickpixel/getcolor.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/mcrypt/constants.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/mongodb/bson/packedarray/fromphp.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/oci8/functions/oci-set-prefetch.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/sockets/functions/socket-read.xml
< f80105b4fc1196bd8d5fecb98d686b580b1ff65d 1 reference/stream/streamwrapper/url-stat.xml
---
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  appendices/filters.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  install/fpm/configuration.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/cubrid/cubridmysql/cubrid-real-escape-string.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/eio/functions/eio-chmod.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/eio/functions/eio-poll.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/ev/depth.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/ev/run.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evchild/construct.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evloop/run.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evstat/attr.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evstat/createstopped.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evstat/set.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evtimer/construct.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evtimer/createstopped.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evtimer/set.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/ev/evwatcher/clear.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/event/eventbufferevent/construct.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/event/eventbufferevent/setwatermark.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/event/eventconfig/setmaxdispatchinterval.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/event/eventdnsbase/parseresolvconf.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/event/eventdnsbase/setsearchndots.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/filesystem/functions/stat.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/imagick/imagickpixel/getcolor.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/mcrypt/constants.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/mongodb/bson/packedarray/fromphp.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/oci8/functions/oci-set-prefetch.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/sockets/functions/socket-read.xml
> f80105b4fc1196bd8d5fecb98d686b580b1ff65d  reference/stream/streamwrapper/url-stat.xml
1785,1788c1785,1788
< 9d6701a7205c16fc24062e90e2508bb498fbdac5 1 reference/pgsql/functions/pg-enter-pipeline-mode.xml
< 9d6701a7205c16fc24062e90e2508bb498fbdac5 1 reference/pgsql/functions/pg-exit-pipeline-mode.xml
< 9d6701a7205c16fc24062e90e2508bb498fbdac5 1 reference/pgsql/functions/pg-pipeline-status.xml
< 9d6701a7205c16fc24062e90e2508bb498fbdac5 1 reference/pgsql/functions/pg-pipeline-sync.xml
---
> 9d6701a7205c16fc24062e90e2508bb498fbdac5  reference/pgsql/functions/pg-enter-pipeline-mode.xml
> 9d6701a7205c16fc24062e90e2508bb498fbdac5  reference/pgsql/functions/pg-exit-pipeline-mode.xml
> 9d6701a7205c16fc24062e90e2508bb498fbdac5  reference/pgsql/functions/pg-pipeline-status.xml
> 9d6701a7205c16fc24062e90e2508bb498fbdac5  reference/pgsql/functions/pg-pipeline-sync.xml

Enable "doc-uk" build

Since the Ukrainian translation build has been fixed, please enable it.

php ../doc-base/configure.php --with-lang=uk

configure.php: $Id$
PHP version: 8.1.2-1ubuntu2.18

Checking for source directory... /home/mproshchuk/phpdoc/doc-base
Checking for output filename... /home/mproshchuk/phpdoc/doc-base/.manual.xml
Checking whether to include CHM... no
Checking for PHP executable... /usr/bin/php8.1
Checking for language to build... uk
Checking whether the language is supported... yes
Checking for partial build... no
Checking whether to enable detailed XML error messages... no
Checking libxml version... 2.9.13
Checking whether to enable detailed error reporting (may segfault)... yes
doc-base: 7060d52b08d51e5420dfe59a66f4aa0b4d584309
?? fileModHistory.php
en:       539a9823a805ac29cab7fa4baf3ae3a28116a2f5
uk:       23b7acf3c912ea74eb7189d1c9dd543597bee926

Generating /home/mproshchuk/phpdoc/doc-base/manual.xml... done
Generating /home/mproshchuk/phpdoc/doc-base/install-unix.xml... done
Generating /home/mproshchuk/phpdoc/doc-base/install-win.xml... done
Generating /home/mproshchuk/phpdoc/doc-base/scripts/file-entities.php... done
Iterating over extension specific version files... OK
Saving it... OK
Iterating over files for sources info... OK
Generating sources XML... OK
Saving sources.xml file... OK
Modification history file /home/mproshchuk/phpdoc/en/fileModHistory.php not found.
Creating empty modification history file...done.
Creating file /home/mproshchuk/phpdoc/doc-base/entities/file-entities.ent... done
Checking for if we should generate a simplified file... no
Checking whether to save an invalid .manual.xml... no
Loading and parsing manual.xml... done.
Running XInclude/XPointer... done. Performed 1444 XIncludes
Validating manual.xml... done.

All good. Saving .manual.xml... done.
All you have to do now is run 'phd -d /home/mproshchuk/phpdoc/doc-base/.manual.xml'
If the script hangs here, you can abort with ^C.
         _ _..._ __
        \)`    (` /
         /      `\
        |  d  b   |
        =\  Y    =/--..-="````"-.
          '.=__.-'               `\
             o/                 /\ \
              |                 | \ \   / )
               \    .--""`\    <   \ '-' /
              //   |      ||    \   '---'
         jgs ((,,_/      ((,,___/

 (Run `nice php ../doc-base/configure.php` next time!)

Outdated Informix reference urls

The two urls below (both used in reference/pdo_informix/reference.xml for https://www.php.net/manual/en/ref.pdo-informix.php and https://www.php.net/manual/en/ref.pdo-informix.connection.php) are both currently redirecting to https://www.ibm.com/support/pages/publications-ibm-informix-dynamic-server-10-family-products. Someone who is more familiar with Informix should figure out updated links for the intended content.

<!ENTITY url.informix.connectionstring "http://publib.boulder.ibm.com/infocenter/idshelp/v10/topic/com.ibm.odbc.doc/odbc66.htm#sii02998361">
<!ENTITY url.informix.dsn "http://publib.boulder.ibm.com/infocenter/idshelp/v10/index.jsp">

this is a doc-base issue.

The commit:
f315a3b

This change ignores a [skip-revcheck]'ed commit and makes the previous commit the current commit. Therefore, the label cannot do its job. You can see the result of this in the last 'revcheck.php ru' output.
Although the last commit of reference/intl/collator/compare.xml is labeled [skip-revcheck], the file is not ignored and it's listed.

The commit should be revert.

Problematic DTD's

Docbook-DTD customization is inevitable for large projects.
In DTD customization, ENTITYs can be customized, while ELEMENTs that are not wrapped with ENTITYs cannot. In the latter case, it will no longer be the standard DocBook DTD as the ELEMENTs to be modified are wrapped with ENTITYs.

As a result, there is no choice but to hack the DTD. Then we can make the DocBook DTD our own DTD by placing the original copyright and license information at the beginning of the file, specifying the copyrights associated with the modification and that it is a derivative, and start adding the changes required by our document tree to the DTD.

As for the RELAX-NG/DTD application,
· DTD's conformity to the document tree (xmllint),
· conformance of the document tree to DTD (xmllint), and
· conformity of document tree to RNG (jing)
needs to be tested. The last two alone cannot catch all errors.
That is, it is necessary to generate an RNG from DTD (trang).

After all, it is clear that the PDF generation tools prepared for the standard DocBook-DTD cannot be used.