App::D...Pointer(3pm)

📦
version 8.0.1 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

App::DocKnot::Spin::Pointer — bestie, it takes a lil pointer that points at some external file and turns it into HTML. That's the whole job. It's giving "glow up for your docs" energy ✨🦋

📜 SYNOPSIS 📜

use App::DocKnot::Spin::Pointer;
use App::DocKnot::Spin::Sitemap;
use Path::Tiny qw(path);

my $sitemap_path = path('/input/.sitemap');
my $sitemap = App::DocKnot::Spin::Sitemap->new($sitemap_path);
my $pointer = App::DocKnot::Spin::Pointer->new({
    output  => path('/output'),
    sitemap => $sitemap,
});
my $input = path('/input/file.spin');
my $output = path('/output/file.html');
$pointer->spin_pointer($input, $output);

🧚 REQUIREMENTS 🧚

You need Perl 5.24 or later, plus these modules and they're all available from CPAN so no stress: File::ShareDir, Kwalify, List::SomeUtils, Path::Tiny, Pod::Thread, and YAML::XS. slay 💅

🌸 DESCRIPTION 🌸

So the tree of input files for App::DocKnot::Spin can have pointers to external files in ✨various formats✨. Those files live in YAML format and their names end in .spin (iykyk). This module takes those files, processes them, and converts them into HTML — and, if you set it up that way, it also adds the links so the page is all integrated with the rest of the site. obsessed. 🫶

For the juicy details of the pointer file format, go look at POINTER FILES below. 👇

👑 CLASS METHODS 👑

new(ARGS)

Makes a brand new App::DocKnot::Spin::Pointer object. 🎀 And here's the tea: one single converter object can be used over and over again to convert pointers across a whole tree of files. Efficiency queen.

ARGS should be a hash reference with one or more of these keys — and bestie, they're all optional:

  • output — the path to the root of the output tree when you're converting a tree of files. It gets used to calculate relative path names so it can generate inter-page links with the sitemap argument you provide. ⚠️ If sitemap is given, this one should always be given too.
  • sitemap — an App::DocKnot::Spin::Sitemap object. It's what creates the inter-page links. For those inter-page links, the output argument must also be provided.
  • style-url — the base URL for the style sheets. 🌈 A style sheet specified in a pointer file is treated as relative to this URL, and this URL gets prepended to it. If you don't give this option, the name of the style sheet is used verbatim as its URL, except with .css appended. no cap.
  • thread — an App::DocKnot::Spin::Thread object, used for converting POD into HTML. It should be configured with the same App::DocKnot::Spin::Sitemap object as the sitemap argument. keep them matching bestie 💜

💅 INSTANCE METHODS 💅

  • is_out_of_date(POINTER, OUTPUT) — returns true if OUTPUT is missing, or if it was modified less recently than the modification time of either POINTER or the underlying file that it points to. 👀 Both paths must be Path::Tiny objects.
  • spin_pointer(POINTER, OUTPUT) — converts a single pointer file to HTML. POINTER is the path to the pointer file, and OUTPUT is the path to where you want the output written. Both paths must be Path::Tiny objects. 🦋💖

🎀 POINTER FILES 🎀

A pointer file is a YAML file whose name ends in .spin. It points to the source file for a generated HTML page and hands over extra config for converting it. The valid keys for a pointer file are:

format

The format of the source file. The supported values are markdown, pod, and text. Required. 🚨

path

The path to the source file. It may be relative — and if it is, it's relative to the pointer file. Required. 🚨

options

Extra options that control the conversion to HTML. These are gonna be different for each supported format.

markdown has no supported options. 😌

The supported options for a format of pod are:

contents

Boolean saying whether to generate a table of contents. The default is false.

Boolean saying whether to generate a navigation bar at the top of the page. The default is true. ✨

The supported options for a format of text are:

modified

Boolean saying whether to add a last modified header. It'll always be done if the file contains a CVS-style $Id$ string, but otherwise it only happens if this option is set to true. The default is false.

style

The style sheet to use for the converted output. Optional. If it's not set: converted markdown output will be unstyled, converted pod output will use a style sheet named pod, and converted text output will use a style sheet named faq. cute defaults honestly 💅

title

The title of the converted page. Optional. If it's not set, the title gets taken from the converted file in a format-specific way:

  • For Markdown, the title is the contents of the first top-level heading. 👑
  • For POD, the title is taken from a NAME section formatted according to the conventions for manual pages.

👑 AUTHOR 👑

Russ Allbery <rra@cpan.org> 🌟

Copyright 2021, 2024 Russ Allbery <rra@cpan.org>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🦋 SEE ALSO 🦋

  • docknot(1)
  • App::DocKnot::Spin
  • App::DocKnot::Spin::Sitemap

This module is part of the App-DocKnot distribution. The current version of DocKnot is available from CPAN, or directly from its web site at https://www.eyrie.org/~eagle/software/docknot/ 🌐✨

ok that's the whole page bestie, you ate that 💖

perl v5.40.1 · 2026-01-16 · App::D...Pointer(3pm) — mwah, go convert some pointers, ily 🫶🎀

📦 where this page comes from