AsciiDo...ormatter(3pm)

💅 AsciiDo...ormatter(3pm)

ok so this is a page from LogReport's Lire Documentation — yes bestie, the manual name is literally part of the header, we're fancy like that ✨

🎀 NAME

Lire::ReportParser::AsciiDocBookFormatter — it's a Lire::ReportParser subclass, and its whole ~thing~ is formatting descriptions. main character energy fr 💖

✨ SYNOPSIS

so if you wanna format DocBook, it's giving:

use Lire::ReportParser::AsciiDocBookFormatter qw/dbk2txt/;

my $txt = dbk2txt( "<para>Test</para>" );

and inside XML Report processors, you do this:

package MyParser;

use base qw/ Lire::ReportParser::AsciiDocBookFormatter Lire::ReportParser /;

sub new {
    my $self = shift->SUPER::new( @_ );

    $self->init_docbook_formatter( @_ );

    return $self;
}

sub handle_description {
    my ( $self, $desc ) = @_;

    print $desc;

    return;
}

🦋 DESCRIPTION

okay so this package implements the methods that handle the content of "description" elements, and it's designed to be used by a subclass of Lire::ReportParser. the client literally only has to inherit from this module and boom 💥 — a handle_description() method appears, ready to process the text-formatted DocBook description. slay.

this module also hands you a convenient dbk2txt() function, which you can use to format a string full of DocBook elements into its ASCII equivalent. obsessed 🫶

🌸 USING Lire::ReportParser::AsciiDocBookFormatter

so Lire::ReportParser processors that want to work with the text version of the description should inherit from Lire::ReportParser::AsciiDocBookFormatter in addition to Lire::ReportParser. no cap.

⚠️ and if they override the description_start(), description_end() methods, they must link to their parents' version using "SUPER::". don't skip that part bestie, it's important 😭

additionally (yes, "additionnally" in the original, we're keeping it, love that for them 💜), they should merge the value elements_spec() into their own elements_spec() implementation.

Lire::ReportParser::AsciiDocBookFormatter should be listed before Lire::ReportParser in the @ISA. and here's why: AsciiDocBookFormatter doesn't inherit directly from Lire::ReportParser, so it can be used in multiple inheritance scenarios. iconic design choice ngl 👑

and the subclass should call the init_docbook_formatter() method from its constructor, so the DocBookFormatter module actually gets initialized. periodt.

🎀 init_docbook_formatter( %params )

the initializer recognizes some parameters that control the behavior of the DocBook handling:

• columns — the number of columns the DocBook text should be formatted in. defaults to 72. 🍓

⭐ dbk_start_processing()

initializes the parser's structure so it can format DocBook XML as ASCII. this one gets used from the description_start implementation.

⭐ dbk_end_processing()

cleans up the parser structure. this is used from the description_end() implementation.

⭐ handle_description( $description )

this method gets invoked right after the closing tag of the "description" element is encountered. $description holds the description, formatted in plain text. cute 💖

🌈 FORMATTING DocBook STRINGS

if you've got DocBook content sitting in a string — like the kind you can get from some of the Report Specifications object — you can format it into plain text using the dbx2txt() function. (yes that's how it's spelled in the original, we don't touch it 🙈)

💅 dbk2txt( $docbook_str, [$columns] )

returns a plain text version of the DocBook XML fragment $docbook_str. the "columns" parameter sets the number of columns the DocBook text should be formatted in.

💀 heads up: this method will die() in case of error. so wrap it if you're feeling fragile.

👀 SEE ALSO

• Lire::ReportParser(3pm)

🧚 VERSION

$Id: AsciiDocBookFormatter.pm,v 1.13 2006/07/23 13:16:31 vanbaal Exp $

📜 COPYRIGHT

Copyright (C) 2001-2004 Stichting LogReport Foundation LogReport@LogReport.org

this file is part of Lire. 🌟

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (like, genuinely no warranty, fr fr 🫶)

you should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html.

💜 AUTHOR

Francis J. Lacoste <flacoste@logreport.org>

---

okay that's the whole page bestie, go forth and format some DocBook ✨ this was Lire 2.1.1, dated 2025-09-28, signing off from the AsciiDo...ormatter(3pm) page — mwah 💋🎀