sparklemotion/nokogiri

Update parse options to reflect modern libxml usage

Open

#3439 opened on Feb 19, 2025

View on GitHub
 (2 comments) (0 reactions) (1 assignee)Ruby (5,615 stars) (806 forks)batch import
help wantedtopic/documentationupstream/libxml2

Description

Context

In #3360 the libxml2 maintainer left some suggestions about how we're exposing and documenting some of the parse options.

He mentioned:

  • DTDATTR and DTDVALID imply DTDLOAD and are unsafe as well.
  • SAX1 should probably not be exposed.
  • NODICT should probably not be exposed.
  • XINCLUDE, NOXINCNODE and NOBASEFIX are only used by the XML Reader and XInclude API.
  • HUGE is safe these days (since 2.10)

and some forward-looking statements about the upcoming 2.14 release:

  • UNZIP: Enable decompression. This option has no real effect for now. The plan is that users who really need decompression start to add the option. At a later point, it will be required to enable decompression.
  • NO_SYS_CATALOG: Don't use system catalogs when resolving DTDs or entities.
  • CATALOG_PI: Enable oasis-xml-catalog PIs. This is a really obscure feature that should have never been enabled by default. I don't think your users need it.

Actions

I think the actions I'd like to take re: documentation:

  • Make the following bits :nodoc:: SAX1, NODICT
  • Update documentation for DTDATTR and DTDVALID to imply DTDLOAD and include safety warnings
    • And double-check that these are all off by default
  • Update documentation for the XINCLUDE set to specify they're only used by Reader and Node#process_xincludes

And the functional action I'd like to take:

  • Add HUGE to all the default bitsets if the libxml2 version is >= 2.10.0

I'd like to wait until the UNZIP bit is useful before adding it. We don't expose the catalog bits, so nothing to do there.

Contributor guide

Tech stack
ruby
Domain
documentationdeveloper experience
Issue type
refactor
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
RubyNokogiri librarylibxml2 parse optionsunderstanding of :nodoc: and documentation conventions
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Review the suggestions from libxml2 maintainer in issue #3360. Modify the parse options file (likely `lib/nokogiri/xml/parse options.rb`) to mark SAX1 and NODICT as `:nodoc:`, update documentation for DTDATTR, DTDVALID, and XINCLUDE options, and conditionally add HUGE to default bitsets when libxml2 version >= 2.10.0. Ensure all changes are consistent with existing code style.