Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#72 3 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
46/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
php, vim, xml
Área
documentation, tooling

Línea de trabajo

Comienza revisando doc-base/scripts y el archivo xmllint.php y la configuración de Vim propuestos en el issue. Prueba la validación con un archivo XML individual y compárala con el comando existente phd --docbook. Se considera terminado cuando se documente y proporcione una ruta práctica de validación al guardar desde el editor, dejando claro el manejo previsto de las entidades y los errores XML.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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 https://github.com/php/doc-en/issues/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)
Lenguaje dominante
PHP
Estrellas
373
Forks
131
Merge medio
3 d 12 h
PR fusionados (30 d)
8

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de php/doc-base

Todos los issues de php/doc-base

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.