The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Pod-PseudoPod-Book-1.20210620.2051
River stage zero No dependents
/ Pod::PseudoPod::Book::Conf

NAME

Pod::PseudoPod::Book::Conf - configuration options for Pod::PseudoPod::Books

VERSION

version 1.20210620.2051

SYNOPSIS

    # example configuration for the Modern Perl book
    [book]
    author_name=chromatic
    copyright_year=2012
    cover_image=
    language=en
    title=Modern Perl
    subtitle=2011-2012 edition
    filename_template=modern_perl
    build_index=1
    build_credits=1
    ISBN10=0-9779201-7-8
    ISBN13=978-0-9779201-7-4

DESCRIPTION

While Pod::PseudoPod::Book tries to do the right thing by default for all materials, it needs some help for things it can't guess. It also lets you configure some options where the defaults aren't quite right.

When you create a book with the command ppbook create, you'll get a file named book.conf. Edit that and change the values as appropriate for your project. The file is deliberately simple and uses the INI format as understood by Config::Tiny; for more details of the syntax, see that module.

The Book Section

The section marked [book] contains several pieces of information about your work:

  • title is the title of the book.

  • subtitle is the subtitle of the book. Leave this blank if you have no subtitle.

  • language is the IETF language tag which best represents the book's contents. If you're reading this, likely you're fine using en. See RFC 3066 or RFC 4646 for copious detail.

  • cover_image is the path to the image used for the book's cover.

  • author_name is your name. Congratulations!

  • copyright_year is the effective copyright year. If it takes you a while to write the book, feel free to increment this value when you publish.

  • filename_prefix is the filename prefix used to manage multiple bok files for various editions, sizes, or layouts. This makes more sense in the LaTeX world, where the Modern Perl book uses a prefix of modern_perl and has modern_perl_letter.tex, modern_perl_a4.tex, and modern_perl_6x9.tex with the appropriate paper sizes and margins. The default value of book is usually sufficient.

  • ISBN10 is the 10-digit (legacy) ISBN for the work. If you haven't registered an ISBN, ignore this. (If you have registered an ISBN, you should get an 10-digit ISBN for free when you registered your 13-digit ISBN.)

  • ISBN13 is the 13-digit (modern) ISBN for the work. If you haven't registered an ISBN, ignore this.

  • build_index is a boolean flag which controls whether to build and include an index, when possible. This is great for technical and non-fiction works, but works of fiction don't get much value from it.

  • build_credits is a boolean flag which controls whether to turn a CREDITS file in the top-level directory into a credits.pod file woven into the built chapters. Modern Perl does this. You may not need it.

  • build_chapters is a boolean flag which enables the weaving of chapters. If this flag is true, the buildchapters command will use the layout options of your configuration file to build partial chapters into full POD chapters in the appropriate build/ subdirectory. See chapter_build_dir.

The Layout Section

The section marked [layout] contains several pieces of information about the directory structure used to manage the work. Note that if you change these after creating your book with the create command, you may have to create new directories by hand--or at least symlink them. The current configuration options are:

  • subchapter_directory is the directory beneath which you store chapters and their pieces. As ppbook processes chapter files and weaves in subchapters, it must find them somehow. Here's where. The default value of sections is usually fine, but for other uses sometimes a different name is more semantically relevant.

  • chapter_name_prefix is the prefix of all top-level chapter names in subchapter_directory. These files may contain links to other POD files in that directory; when the build_chapters option is true, the buildchapters stage weaves them together and writes the results into the chapter build directory. The default of chapter means that you will create chapters as chapter_01.pod, chapter_02.pod, and so on.

  • chapter_build_directory is the directory under build/ into which the buildchapters command will write all built chapters. The default of pod/ is almost always correct.

The Chapter Order Section

The section marked [chapter_order] is optional. If present, it allows you to specify the order in which individual files should appear in the table of contents of HTML and ePub versions. This is relevant in the case where you have files of different names which do not sort lexigraphically in your preferred order. Due to quirks of how Config::Tiny manages keys and values, you must use sequential numeric keys, with leading zeroes preferred. For example:

    [chapter_order]
    01=endorsements
    02=dedication
    03=acknowledgements
    04=foreword
    05=part_01
    06=chapter_01
    07=chapter_02
    08=chapter_03
    09=chapter_04
    10=chapter_05
    11=part_02
    12=chapter_06
    13=chapter_07
    14=chapter_08
    15=chapter_09
    16=chapter_10
    17=appendix_a
    18=appendix_b
    19=appendix_c
    20=appendix_d

Note the lack of file suffixes.

This feature may change slightly in the future, but it will be present in one form or another.

COPYRIGHT

Copyright 2011-2012 chromatic.

This program is free software. You can redistribute it and/or modify it under the same terms as Perl 5.14 itself.

AUTHOR

chromatic <chromatic@wgz.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by chromatic.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.