Skip to content

docs: clarify toString($format) and no_blanks interaction (GH #234) #285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
toddr-bot wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: clarify toString($format) and no_blanks interaction (GH #234) #285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/libxml.dbk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2510,6 +2510,31 @@ print {$out_fh} $doc-&gt;toString;</programlisting>
<para>If $format is 2 (or higher), libxml2 will act as $format == 1 but it add a leading and a trailing line break to each text node.</para>

<para>libxml2 uses a hard-coded indentation of 2 space characters per indentation level. This value can not be altered on run-time.</para>

<para><emphasis>Important note about formatting and whitespace:</emphasis>
The formatter only inserts indentation between child
elements that are not already separated by text content.
When XML is parsed normally, whitespace between tags
(newlines, spaces used for indentation in the source) is
preserved as text nodes. These existing text nodes prevent
the formatter from adding its own indentation because it
will not alter existing text.
</para>
<para>
To get proper re-indentation, strip whitespace-only text
nodes at parse time using the <literal>no_blanks</literal>
option:
</para>
<programlisting>my $doc = XML::LibXML-&gt;load_xml(
string =&gt; $xml_string,
no_blanks =&gt; 1,
);
print $doc-&gt;toString(1); # now produces indented output</programlisting>
<para>Without <literal>no_blanks =&gt; 1</literal>, calling
<function>toString(1)</function> on a document that was
parsed with default settings will typically return the
XML unchanged, since the original whitespace text nodes
are still present.</para>
</listitem>
</varlistentry>

Expand Down
20 changes: 20 additions & 0 deletions lib/XML/LibXML/Document.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,26 @@ leading and a trailing line break to each text node.
libxml2 uses a hard-coded indentation of 2 space characters per indentation
level. This value can not be altered on run-time.

I<<<<<< Important note about formatting and whitespace: >>>>>> The formatter only inserts indentation between child elements that are not
already separated by text content. When XML is parsed normally, whitespace
between tags (newlines, spaces used for indentation in the source) is preserved
as text nodes. These existing text nodes prevent the formatter from adding its
own indentation because it will not alter existing text.

To get proper re-indentation, strip whitespace-only text nodes at parse time
using the C<<<<<< no_blanks >>>>>> option:



my $doc = XML::LibXML->load_xml(
string => $xml_string,
no_blanks => 1,
);
print $doc->toString(1); # now produces indented output

Without C<<<<<< no_blanks =E<gt> 1 >>>>>>, calling C<<<<<< toString(1) >>>>>> on a document that was parsed with default settings will typically return the
XML unchanged, since the original whitespace text nodes are still present.


=item toStringC14N

Expand Down
Loading