Skip to content

Latest commit

 

History

History
319 lines (291 loc) · 18.6 KB

WORKLOG.adoc

File metadata and controls

319 lines (291 loc) · 18.6 KB

WORKLOG

  • use Groovy language specification as case study to find corner cases

    • perhaps progit2 as well; others?

TODO

  • recto/verso margins

    • account differences in top/bottom margins on recto/verso pages in running header/footer

    • dry runs need to reflect current recto/verso margins; situation can get complex if they differ

    • get import_page to stop adding an extra page

    • blank page after title page if media=print

  • document missing keys in theming guide for 1.5.0.beta.1 (table seems to missing some)

  • enable key table_font_style

  • check that color of table edges set to table_grid_color??

  • create value type for font style and font alignment for theming guide

  • force encoding of theme to UTF-8 (particularly for keys related to content)

  • be more consistent with how examples are shown in theming-guide.adoc (do we show last segment only?)

  • document theme-related AsciiDoc attributes in theming-guide (#428)

  • allow top as alternative to margin_top for all elements on title page (#431)

  • add feature to number bullets according to section number (needed for OpenDevise agreement)

  • swallowing exceptions! (any use of e.message in a string is dangerous)

  • allow ordered list marker to be prefixed by section number (a global setting?)

  • conum not aligned vertically with callout text (perhaps too small?)

  • decouple theme settings for section titles and discrete headings

  • table should expand to 100% if "spread" role is set

  • replace explicit char ranges with classes in regexp (e.g., or \w)

  • test Rouge upgrade (should address workaround we have in encoder)

  • devise a way to specify a value as a string literal (variable replacement only) in theme

  • prawn-gmagick (fixes PNG transparency issue); don’t fail-fast on gif if gem is detected

  • document pdfwidth in themeing guide (currently no mention of it)

  • convert "-" in variable name in theme to underscore (e.g., $base-font-size)

  • apply calculated theme values after loading?

  • allow "content" in place of recto_content & verso_content for running header/footer

  • allow image to span width of page (role=canvas, role=canvas-x or role=canvas-y); if role is canvas or canvas-y, then it does not consume height

  • allow valign value to be a number (requires change to Prawn)

  • layout SVG without using keep_together (since we know all the dimensions)

    • fix SVG to a single page (check height + caption height)

  • allow background color to be set for heading

  • allow border to be set around block image

  • switch wolpertinger to howling wolf mouse

  • support arbitrary numeric entities (convert to unicode)

  • add brief mention in theming guide that deeper customizations can be achieved by extending the converter

  • allow alignment of list to be set separately from base align (and perhaps a hint in document)

  • due to order of loading, getting warnings when redefining methods in Asciidoctor core

  • prawn-pdfimage https://github.com/packetmonkey/prawn-pdfimage

  • rename ThemeLoader to ThemeReader?

  • document autofit option on verbatim blocks

  • document how to extend the converter, use Prawn

  • using tabs instead of spaces for source code indentation allows leading whitespace to be preserved when copying

  • margin per heading level (see asciidoctor#176)

  • document how to override the Ruby code to get custom styling in the theming guide

  • convenience method to check if there’s enough room for another line on page

  • allow font size in theme to be specified in em or %

  • allow dynamic background image with page number in path

  • running header/footer covers content (perhaps just a limitation that needs to be documented)

  • document that palette-based transparent in PNGs is not supported

  • create document that explains how built-in fonts are generated and what subsets are selected

    • document in theming guide what must be done to prepare fonts (old-style 'kern' table, optionally subset) (file issue!)

  • add broader character range to monospace font so we can drop fallback font by default (#282)

    • consider having a fallback for prose and fallback for literal

  • file issue for prawn to preserve space (even w/ guards, spaces don’t preserve over wrapped lines)

    • if this is fixed, we can remove all the guard indent code

  • file issue for prawn to support spacer fragments with fixed width / height and no text (or text is ignored in calculations)

  • file issue that prawn-svg messes with the cursor (need to explain how)

  • document limitations in README (such as no linear gradients in SVG, embedded images in SVG must be URL or inlined, PNGs must be flattened, etc)

  • document all permutations of image sizing

  • set vposition on title page logo image explicitly to avoid page overrun?

  • verse has problems with wrapping if line is long

  • allow default kerning to be set using theme

  • table column header is wrapping by char (verify?)

  • implement margin collapsing (between blocks)

  • rework pull request for source line numbers (combine with restore conum logic if conums are enabled)

    • also combine with the preserve_space logic

  • allow front cover and back cover image to be defined in theme; document in theming-guide

  • should we shorted the keys to front-cover and back-cover (since image is implied?)

  • keep caption with table (check for sufficient space)

  • allow caption placement for table to be configurable (top vs bottom)

  • allow valign to be set on image block (vertical center in page for things like slides)

  • separate theme control for listing vs literal block (and maybe source too)

  • allow title page image "bottom" to be set instead of "top" (mutually exclusive)

  • rtl (see ./sandbox/rtl/ folder)

  • rewrite optimize-pdf using rghost

    • add Optimizer class; wire to cli

  • what do we do if the image type cannot be resolved from file extension (i.e., when target is a URL)?

  • pass macro doesn’t work in source block when macro subs and highlighting are both enabled (#180)

  • enable cache_images option for prawn-svg (#223)

  • bind image_registry between scratch and main document so we don’t process the same image more than once

    • need to do some testing

  • show SVG warnings if debug (or trace) is on

  • prawn SVG doesn’t support relative paths for nested images (must be http, https or data) (update README)

  • clean temporary files once per conversion? (file issue)

  • clear font paths in SVG interface so it doesn’t scan system? (since it’s not portable anyway)

  • title is being rendered 3 times (maybe one for scratch?); explain why in comments if normal

  • finish docs/theming-guide.adoc

    • continue working on json schema for theme; try to generate keys section from it

  • rethink how we’re handling line heights for fonts, then document carefully

    • look closer at line_height and line_height_length and see if we need to document other details

  • implement first-line indent for paragraphs (seems like conflict w/ our text formatter)

    • option to not indent first paragraph in section

    • if you indent, perhaps drop the margin between paragraphs?

  • add index support

  • add entry to TOC for preamble/preface

  • can we create fragments in converter instead of using the formatted text parser?

  • allow text alignment of prose to be set in document

  • don’t issue warnings on scratch document

  • rake release seems messed up (tagging the wrong commit)

  • getting a line wrap break before comma if preceding word is emphasized (problem in Prawn wrapping)

  • toc

    • make dot leader style separate from title / number

  • running content

    • side margins (allow override, default to content margins)

    • numbered and unnumbered chapter and section titles (file issue)

    • chapter and section number (easily solved by previous)

    • separate running content for chapter page (by default uses normal content)

  • should we rename base_ to body_ to make it more familiar to CSS developers?

  • support !include in theme file (file issue)

  • add cover page example to chronicles so people see how to use it

  • don’t orphan a single line of paragraph (send it with a buddy line)

  • implement stem support

  • fail gracefully if theme file cannot be found

  • expose theme variable on document (attr_reader?)

  • nested unordered list items should use different marker

  • dedicated style for top/bottom margin of outline list

    • allow margin top and bottom to be set for lists (applies to outer-most list)

    • allow spacing between nested lists levels be configured in theme

  • need dedicated theme styles for paragraph spacings, etc

  • can’t put margin top on chapter (chapter_top?)

    • chapter / heading background color

  • recto/verso indentation (on body?)

  • don’t indent and draw line next to quote block unless width > 0 or color != transparent

  • subtitles for chapters

  • part titles need their own page and styling

  • add color calculation functions in theme file (like in SASS)

  • create utility method to get % offset of page as y value (option to constrain to bounds)

  • document converter assignment in convert_content_for_block method

  • support transparency for colors (this is now supported by resolve_theme_color)

  • support generic color (or value) attribute in formatted text parser instead of specific color systems (rgb, cmyk)

  • allow theme_font to set line_height (honor this setting from document)

    • theme setting for code line height (currently using base_line_height)

  • should we put an entry for doctitle in the outline if notitle is set? (need to test these edge cases)

  • use docdate attribute to set modification date on document (file issue)

  • add more theme control over toc (font size, style, color per level)

  • don’t allow formatted text (e.g., monospace) in toc entries

  • prevent title-logo-image from spilling to next page (same with title content)

  • document what each keep_together is doing / expects

    • keep_together really needs to pick up the inherited horizontal bounds or else measurement is inaccurate

  • code cleanups (regexps to constants, nil? checks and such)

    • split prawn_ext/extensions into individual files based on function

  • enable line above (or below?) title on title page (file issue)

  • enable text_transform for table foot row

  • file upstream issue for Prawn to warn if it can’t resolve a glpyh (or monkeypatch it)

  • support web fonts; use uri-cache to avoid redundant fetching

  • align caption to match alignment of block image

  • allow pdf-page-layout (portrait || landscape) to be set in document

  • allow pdf-page-margin to be set in document

  • attribute or role to control table shading (all, even, odd) (or call it striped like bootstrap?)

  • make conum glyphs configurable in theme (use reference table to resolve)

  • do we still need the converter hack in convert_content_for_block? (seems to be needed for admonitions)

  • avoid getting an empty last page (example: colist at bottom of page can cause this)

  • utility to coerce the color value transparent to nil (better handling in general)

  • CJK and/or multilingual support

  • description list term should keep together with content (file issue)

  • hardbreak in table cell results in extra endline (likely not normalizing cell content)

  • remove pdfmarks file after optimizing

  • add note to README that Prawn will subset any fonts provided

  • look into single_line + shrink_to_fit in listings, perhaps other places

  • refactor as Prawn view to avoid method name conflicts (also see prawnpdf/prawn#802)

  • make CodeRay theme colors configurable (in theme?) (now that we have Rouge, this may be obsolete)

  • create proper default (Asciidoctor) theme

  • document how the treetop parser is rebuilt

  • use ImageMagick to uncompress PNG images before reading them (could also just document this)

  • rework font so we can set actual height, calculate x_height internally (use 1em for spacings)

  • padding top and bottom on content affects height_of calculations (need to review)

  • code font needs to support more than just ascii (Golo license block is an example)

  • don’t cutoff content in partintro

  • admonition styles are one big hack; need to be organized and based on theme

  • add admonition_label_font_color to theme

  • autofit logic not working with Courier (still overrunning line)

  • honor safe mode rules

  • allow cover images to be specified by theme as a fallback

  • verify cover image exists; fail gracefully with warning

  • stop using fallback fonts in default theme (instead, bundle a fuller font)

  • print scratch.pdf file if verbose / trace mode is on in Asciidoctor

  • introduce setting to indent section content

  • rename default theme to docbook theme, make default the Asciidoctor theme (should we have a base theme?)

  • allow relative font size for inline code to be set (perhaps a percentage or em value? there are problems with this in arranger)

  • set defaults in ThemeLoader for required theme settings like prose_margin_top/bottom so we don’t need fallbacks in code

  • implement orphan sentences for paragraph

  • apply line height metrics for table content

    • figure out how to adjust line height for monospaced cell content

    • figure out how to layout regular cell content to adjust for line height

  • document the typeset_text methods very clearly

  • move check for node.title? inside layout_caption

  • theme idea / tester: see sandbox/ebook-learn_version_control_with_git-SAMPLE.pdf

  • make alternating page title position optional (via theme?)

  • BUG: page numbers are off in Clojure Cookbook

  • fix passthrough placeholders that get caught up in syntax highlighting (see https://github.com/asciidoctor/asciidoctor/blob/master/test/blocks_test.rb#L2258-L2277)

  • we could eliminate some of the tags we’re currently matching in the formatted text parser (e.g., link)

  • add Preamble to TOC

  • NOTE prawn-svg supports loading from a URI (only applies to embedded images)

  • honor font defs in SVG (to get M+ 1p); prawn-svg supports loading fonts; need to pass fonts to prawn-svg

  • should we support % as a unit in theme (divides by 100 and sets float value)?

  • disable monospace color in headings

  • add source language to upper-left corner of listing block

  • enable pagenums attribute by default (may require changes to how we handle attributes)

  • start page numbering on first page if no title page

  • implement quote style from default Asciidoctor stylesheet

  • reorganize Prawn extensions (see prawn-table for example)

  • rename "theme" to "style"?

  • restrict custom theme path to jail (or load from load_path)

  • implement convert_toc

  • can get orphan conum if starts on last line of page (fixed already?)

  • only create title page if doctype=book

  • italic text in a line of text styled as bold in the theme loses its bold style

  • introduce method for start_initial_page?

  • make outline a document option (perhaps "outline" like "toc")

  • shrink / squeeze source code to avoid wrapping (see original impl in nfjsmag, also shrink_to_fit)

  • add bench/ directory for the script to test the speed of the formatted text parser

  • start page numbering on page 1 (use /PageLabels reference to make i the title page number)

    • add this feature upstream to Prawn

  • report image only page w/ stamps corruption issue to Prawn

  • add /PageMode /UseOutlines

  • what does fopub do to calculate scaling images? reduces width more?

  • replace tabs with spaces in source code (Asciidoctor core change?)

  • preamble on separate page?

  • part on separate page for book doctype? (which other sections?)

  • make default image scale width a theme setting

  • cli arguments

    • theme (pdf-style, pdf-stylesdir)

    • enable/disable writing pdfmarks file

    • optimize-pdf

  • section numbering

  • implement footnotes correctly

  • table footer

  • flesh out outline more

  • flesh out title page more

    • document subtitle (partially solved)

  • don’t create title page for article doctype

  • implement toc and activate if toc is set on document (need to reorder pages)

  • inline image

  • callbacks for title page, new part, new chapter, etc

  • split out render methods for chapter, part, section, etc

  • custom subs in verbatim blocks

  • captions/titles on all blocks that support them

  • make font size and character spacing scaling of inline code part of theme

  • customizable character spacing

  • might be able to avoid dry run for listing/literal in obvious cases

  • implement index of index terms

  • bw theme for CodeRay to match output of Pygments bw

  • inline tabs should be replaced in layout_prose (etc) when normalize is enabled

  • use treetop to parse and evaluate theme file

  • make source code highlighting theme configurable (should be now, but has problems with conums)

  • use or don’t use pad method? check performance

Documentation

  • control page numbering using pagenums attribute

  • "Incorrect number of arguments in 'SCN' command" happens when you add a stamp to an imported page

  • be mindful that layout_prose adds margin to bottom of content by default (important when working in a bounding box)

  • ttfunk does not support ligatures (e.g., fi → fi); we could do this manually in post_replacements

API notes

  • if we set the vposition to a numeric value, it skips the overrun check that happens internally

Potential Optimizations

  • if autofit is set on a listing/literal block that has conums, we are splitting fragments by line twice

Usage Optimizations

  • uncompress PNG files to avoid slow zlib inflating step in Prawn

  • flatten PNGs (remove alpha channel) since it messes up font rendering on the page in Adobe Acrobat Reader (need to verify)

  • avoid the fallback font if possible (use full fonts in your theme) because it checks for every glyph

  • font families used in SVGs must match keys in the font catalog

Open Questions

Design

  • remove/reduce padding above heading when it appears at the start of a page?

  • Default line height?

  • Should the heading sizes be calculated according to the default font size?

  • Page margins

  • Body indentation?

    • recto / verso indentation?

  • Size of masthead / footer

  • Line separating masthead / footer?

  • Separate title page

  • Start chapter on new page?

  • Special layout for chapter page?

Theme

  • keep or drop base_ prefix in theme? I think we should keep it because it provides context elsewhere in the document (e.g. $base_font_size vs $font_size)

Notes

  • "section title" is the semantic element; "heading" is the structural element