Skip to content

Latest commit

 

History

History
557 lines (521 loc) · 37.6 KB

WORKLOG.adoc

File metadata and controls

557 lines (521 loc) · 37.6 KB
Raw

WORKLOG

TODO

  • allow prose alignment to be set

  • should text alignment on list inherit to nested lists?

  • add bw / grayscale theme for rouge (upstream?)

  • fix labels in issue tracker to match other projects; in particular, enhancement should be green.

  • setup asciidoctor-mathoid project, then mention it in the STEM support section

  • QUESTION should we show keys with hyphens instead of underscores in theming guide?

  • add preamble to toc

1.5.0.alpha.17

  • switch to new logging subsystem (and verify we can use --failure-level option)

  • document rouge-style in README (already in theming guide, but gets buried)

  • pass current styles downwards when parsing formatted text (see asciidoctor#854)

  • test suite

  • start the README with a proper introduction to Asciidoctor PDF (and not so focused on Prawn)

  • support unnumbered and no-bullet style on ordered list

  • implement SVG fit for background image (#765)

  • add helper to expand value into 4 coordinates (top, right, bottom, left)

  • not honoring align in abstract

  • don’t style paragraph after abstract paragraph as lead (right?)

  • be able to control padding per column in footer

  • should we reroute String#downcase if unicode gem is loaded? this is required for natural cross references; or should we just document workaround?

  • if sourcemap is enabled, error messages should include whatever line information is available

  • CRITICAL: prawn-svg upgrade broke sizing of title logo image; blocking release

  • Prawn reports unknown blank font if family is valid but style is invalid (see prawnpdf/prawn#1022)

  • catch UnsupportedImageType and issue warning that suggests using prawn-gmagick; see sandbox/interlaced.png

  • something like prawn-gmagick in Java env

  • look for image in imagesoutdir if set and the image cannot otherwise be resolved

  • in follow-up to #271, mention that images are resolved at the time of conversion; thus, they need to be located where the converter can find them; that often means setting imagesdir to an absolute path

  • split out the background fill from PR 664 into a separate PR to merge sooner

  • apply logic for convert_sidebar to convert_example

  • vertical centering in table cell w/ Noto Serif is off (set align to vertical center for a single-line cell)

  • import generate-font-subsets.pe script from Asciidoctor EPUB3; rename to generate-bundled-fonts.pe

  • if we assume that any block except a paragraph will "unfloat", we might be able to implement floating images; just mark the "jump to point" for any block that isn’t a paragraph, restrict the width and write

  • update the theme-schema.json (or remove it)

  • have some sort of threshold for how close we get to bottom of page before advancing when starting new block

  • look where else we should be using advance_page instead of start_new_page

    • do we really need advance_page when drawing background? isn’t that always forging a new page?

  • toclevels=0 should show parts only (to be consistent with HTML); currently shows nothing (#783)

  • define sum on core_ext/array to optimize for Ruby 2.4

  • allow border bottom of table header row to be set by theme

  • vertically center background image by default (yes?)

  • add link to jump back to origin of bibref from bibliography (effectively a back link)

  • stroke and fill multi-page sidebar block (#259) and example block (#362)

    • see PR

  • part/chapter/section start pages are calculated twice, once for each running content; should be shared

    • probably need to introduce a model object to hold the cache

  • line height in TOC is too small if heading only contains monospaced text

  • UPSTREAM: rouge treats a CSS property as a Name::Label instead of a Keyword (see rouge-ruby/rouge#665)

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

  • transform table cell text inside correct font context (allows us to check the current font, such as in breakable_uri)

  • should we drop "<font>" handler in formatted text transform?

  • ttfunk 1.5.0 chokes on narrow no-break space char \u202f (patch applied; prawnpdf/ttfunk#39)

  • implement text transform for running content (#702)

  • implement line highlighting in rouge (#681)

  • should we allow the template/format of the line number in the source listing to be controlled using a sprintf template?

  • only nest outline inside of root if doctype=article (still valid?)

  • warn if image in running content can’t be found (#731)

    • only report failure to embed image in running content once

  • allow vertical_align to be numeric in running content

    • Prawn formatted_text_box doesn’t support a numeric value for :valign; need to add upstream (or patch)

  • allow color and string template to be specified for alt text (#730)

  • if image fails to load, could draw a box with an X in it to indicate it’s broken

  • enable fit=scale-down (or fit=contain) for title logo image; otherwise, just let it get clipped (will require passing at option to embed_image to prevent page from advancing)

  • add option to force margin (to apply even when at top of page)

  • make section depth for section-title attribute in running content configurable (#726)

  • add ability to set watermark_image which goes on top of each (non-imported) page instead of bottom (#727)

  • AsciiDoc table cell leaves padding below last block (due to no margin collapsing)

  • M+ 1mn box drawings have width of 1000 instead of 500, so they don’t draw box correctly (see prawnpdf/prawn#1002)

    • looks like we’re going to have to patch the font to draw the box lines correctly in a 500x860 space

    • might want to file this upstream

  • rewrite optimize-pdf using rghost (#535) (also see #21 and #22)

    • prototype implemented!

    • add Optimizer class; wire to cli (separate issue?)

    • we could recommend using HexaPDF with some sample code in README, but we can’t integrate it since it’s AGPL

  • QUESTION: should we defer image dimension assignments to calc_image_dimensions for raster images (similar to resize from Prawn SVG)

  • passing align to layout_heading leads to ugly code

  • we could support the big and small roles on phrase by mapping to base_font_size_large and base_font_size_small

  • allow height of inline image to be set to line height (perhaps 1em?) (#711)

  • add support for file root / web requests for inline SVGs (#683)

    • also, disable file requests when safe mode is secure

  • FILE ISSUE: support transparent background colors (e.g, f5f5f580)

    • might have to switch to rgb, rgba, cmyk, cmyka instead of arrays; or 2D array?

  • need custom cell impl to handle paragraph breaks in table cell properly

  • what should we set as the border color if the source highlighting theme has a background color?

  • use fdiv instead of forcing numeric to float

  • use the keyword "normal" instead of "regular" to refer to the non-styled font file

  • make sure any state is cleared after conversion, including attributes assigned

  • height of listing block not calculated correctly when string of contiguous characters exceeds length of line

    • put listing block with very long line inside of sidebar; see that sidebar height is incorrect (too large)

    • is this because source highlighting is not done in scratch document?

  • add line swell when drawing dashed line on listing block

  • rework resolve_image_path API so it’s more logical; override based on type of first argument; document as option

  • rename text-alignment attribute to text-align? (change is within alpha.14, so still a chance to change)

  • report cursor / bounding box bug in column_box

  • introduce theme keys for styling index

  • index term that wraps should have a hanging indent (#645)

  • rename inherited_align to text_align? (and base_align to base_text_align?)

  • make sure any state is cleared after conversion, including attributes assigned

  • when removing callout numbers, also remove the leading space so we don’t mess up the highlighter

    • in particular, messing up highlighting for apache conf file

  • make dpi configurable (controls the px to pt conversion)

  • should we make :px the default units in to_pt? or require explicit units?

  • QUESTION should we cache background color of source highlighting theme?

  • block anchors should be positioned on same page as content if content is forced to new page

    • call theme_margin <type>, :top first

    • theme_margin should return distance moved (0 if advanced to new page)

    • pass effective margin as optional argument to add_dest_for_block to adjust placement

    • already handled for block images

  • QUESTION: should we skip starting new page if image doesn’t fit on whole page?

  • consider using unlink on creation for tmpfile; see http://ruby-doc.org/stdlib-1.9.3/libdoc/tempfile/rdoc/Tempfile.html#method-i-unlink

  • might be faster to not use TextDecorationTable lookup in to_styles (though it’s only called once)

  • if icon is specified, font-based icons are enabled, and value doesn’t end in file extension, assume custom icon name ^ for core

  • look into using close! on tmp file, which will safely unlink

  • justify does not work in normal table cell (and does not inherit from base)

  • support horizontal alignment of AsciiDoc table cell content (need to handle explicitly)

    • only relevant when using subtable since it must have width < cell width

  • format code to align with project standards

  • -v doesn’t turn on warnings soon enough to catch warnings in Asciidoctor/Asciidoctor PDF

    • might need to look ahead at arguments

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

  • keep together lines of a colist item?

  • support image URL (using resolve_image_path) in running content (what about data-uri?)

  • numbering for appendix subsections is not correct; should be A.1, A.2 (#627)

    • seems like an issue in core too

  • BUG: Asciidoctor surrounded by smart quotes doesn’t get translated to a link (as it should)

  • FILE ISSUE: draw border for quote/verse block on right if text is aligned to the right

  • Prawn should not move cursor before placing image if image exceeds height of bounding box

    • ^ workaround in place by overriding move_text_position

  • part title / number (#597)

    • upper roman numeral

    • add part-label, fallback to Part (e.g., Part I)

    • only use roman numeral in toc

  • support equal column widths in header/footer as "columns: 3*" (with optional leading alignment)

  • support padding for each column in running header/footer

  • should we move files under asciidoctor/pdf and use asciidoctor-pdf as the alias? (#262)

  • consider moving RomanNumeral into a gem named roman_numeral

  • should vertical alignment of admonition icon/label should respect padding on content? have it’s own padding?

  • allow general settings for admonition icon to be set using admonition_icon key prefix (e.g., admonition_icon_size)

  • allow alignment to be set on discrete heading using role

  • SIMPLE: mark required theme keys (assume keys are optional by default)

    • required keys can never have a null value; most are set by base theme

  • allow font properties to be set for normal paragraph separate from base (need to think about inheritence)

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

  • use <a id=""></a> instead of <a name=""></a> for anchor point in formatted text

    • benchmark to see if it’s faster to use empty or non-empty element in parser

  • text decoration should be supported as part of theme_font

  • QUESTION: should we set pdf-anchor attribute on every node that has an id?

    • isn’t it required for cross references to work?

  • QUESTION should preface subsection be numbered? (although it is numbered in DocBook and dblatex)

  • new design for keep together; necessary to get exact height accounting for gaps at page breaks

    1. in dry run, set to stop when advancing to next page (override on_page_create to throw exception)

    2. if less than one page, return calculation (similar to what we do now)

    3. if greater than one page, clear on_page_create; move to y offset of original and start dry run again; fix calculation

    4. (if not keeping together, we can skip 1 and 2)

    5. might be able to avoid dry run for listing/literal in obvious cases; engineering estimate

  • lines in a paragraph that splits across a page doesn’t have proper line height shift

  • rename "convert_content_for_" since it can collide with existing blocks; don’t start with "convert_"

  • don’t orphan block title (make sure anchor stays with start of block)

  • QUESTION should we report full image path of gif in warning message when prawn-gmagick is not available?

  • QUESTION should we add destination to top of imported PDF page?

    • import page should accept id as section, optional argument

  • leading (line height) isn’t applied when content is split across pages

  • generate fonts without PS Glyph Names to reduce file size

    • create script that can generate fonts entirely from original font source

  • if start_new_page is called at end of layout_chapter_title, and media=prepress, ghostscript reports an error

    • problem is no color space is set; can fix by calling update_colors before advancing to recto page in start_new_chapter

    • maybe introduce a skip_page helper to combine these operations?

    • upstream issues: prawnpdf/prawn#951 and prawnpdf/prawn#473

  • document how to test / use a PR

  • allow font size of dot_leader to be specified (some risk if it exceeds size of entries)

  • add empty? method to Page (instead of page_empty? on document)

  • UPSTREAM: add option to svg method to not move cursor (in prawn-svg)

  • UPSTREAM: in prawn: go_to_page should accept second argument that is cursor position (can we patch?)

  • UNRESOLVED: dry_run should start at cursor of main document (or as option); total height calculation would need to be revised

    • box_height isn’t currently accurate when it spans more than one page

    • this should fix height calculation when content is split over a page break (leaving small amount of excess)

    • make sure at least one line can be written when code is split or else jump to next page

    • however, if cursor is advanced to fit content on page, then that excess will cause box_height to be too large

    • life would be simpler if Prawn allowed us to draw graphics at bottom layer

  • space around inline anchors/index entries doesn’t get collapsed by text formatter

  • add support for format attribute on image macro to image-related attributes such as title-page-background-image

    • support explicit image format for cover page image and page background image

  • allow background image to be sized and positioned using attributes

  • introduce abstract-title attribute to complement preface-title?

  • need some sort of post_construct method for converter that receives document

    • inline convert methods can get called before init_pdf

    • monkeypatch?

  • document nonfacing option more clearly (in README or theming guide)

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

    • I need instructions for myself so I know how to update/modify the fonts

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

  • consider supporting icon tag in parser to simplify how inline icons are stored; simpler use of passthrough content

  • cache stateless cell data resolved from theme (don’t need to recalc each time; at least per table)

  • FILE ISSUE: autowidth on table doesn’t work for multi-line content (prawn-table bases width calculation on normalized value)

    • table ends up being stretched even though it doesn’t need to be

    • I don’t know a way to determine how much width a block of rendered content occupies

    • see prawnpdf/prawn-table#73

  • table logic: does the layout_table_caption have to be inside the table block? can we pre-calculate the actual width for the caption? does the table offer a callback we can use to keep the caption on the same page as the table?

  • introduce object to store/organize running content data and specs

  • QUESTION: should theme font handle hierarchical keys (either explicitly or implicitly)

  • need to support .canvas role on image so it isn’t shrunk to fit inside top/bottom margins

    • perhaps .canvas, .canvas-x, .canvas-y

    • 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

    • partially addressed by vw units

  • FILE ISSUE: when split source listing, add top padding to bounding box (or is it the line metrics top?)

    • actually, this has to do with the a miscalculation in dry run when not starting from same y position

  • stroke and fill multi-page sidebar block (#259) and example block (#362)

  • support URL images in running content (need to delegate to resolve_image_path)

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

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

  • outline should link to title page if there’s a cover page (skip cover page and ensuing blank page)

  • don’t allow title page content to jump to next page

  • might be better to organize fragments of source chunks by lines (and pass that around) to simplify post-processing

  • support negative start value for list (#498)

    • need to count negative numbers in correct direction

  • support zero-leading integers (use dedicated type like w/ roman numerals) in reversed order lists

  • margins/paddings at page boundaries are strange, fragile

  • implement margin collapsing (between blocks)

    • would eliminate need for negative padding for blockquote

  • bw theme for Rouge to match output of Pygments bw

    • also look at grayscale theme from highlight.js

  • the nested? method on list isn’t checking if nested inside a block inside a list

    • need an example

  • wrapped lines in source listing should be indented to account for line number gutter (#504)

  • add sample SVG to content of chronicles-example.adoc (we do already use one for title page)

  • inline images: allow built-in font family names for SVG to be remapped

  • inline images: should we be passing absolute image path in tag or something relative (or even a lookup id?)?

  • large image runs into running footer (doesn’t bottom margin need to be aligned with running footer height?)

  • should str_to_pt helper handle % and vw units?

  • allow format of printed link to be controlled by theme (similar to what we do in the manpage converter)

  • FILE ISSUE: should not wrap at formatting mark unless it’s at a break opportunity

    • the problem here is that Prawn is allowing breaks at the boundaries of text fragments; it should only look at the contents

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

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

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

  • conum should never wrap (push it into the text if necessary)

  • decouple theme settings for section titles and discrete headings

  • decouple listing/literal/source theme settings; currently all under code

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

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

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

  • apply calculated theme values after loading?

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

    • still relevant after restructuring?

  • be more specific in theming guide as to where prose_margin_top and prose_margin_bottom apply

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

  • allow background color to be set for chapter / heading

  • allow border to be set around block image (#767)

  • file issue in prawn to dispatch to image handler for images it doesn’t know about

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

    • see sandbox/asciidoctor_pdf_extensions.rb

    • reference infoq-minibook repo & blog post

    • document how to extend the converter, use Prawn

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

  • is https://github.com/packetmonkey/prawn-pdfimage a safer way than prawn-templates to import PDF as image?

  • rename ThemeLoader to ThemeReader (or ThemeManager)?

  • normalize step leaves space after endline at a hard line break (doesn’t seem to affect flow)

  • margin per heading level (#176)

  • need a single object to hold complete font properties; different from font family/style object

  • font method should support a single argument that’s a font object or font hash

    • in general, the way font properties are set needs to be cleaned up

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

    • should multiply value being inherited

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

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

  • 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 in older version of Prawn

  • 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

    • we also have a problem that soft hyphens in wrapped content get dropped

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

    • needed for arranging inline objects

  • document limitations in README (such as no linear gradients in SVG, 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 (in what way?)

  • allow default kerning to be set using theme

  • keep line comment in front of callout number to aid copying?

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

    • also combine with the preserve_space logic

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

  • keep caption with table (check for sufficient space); only for top placement since bottom placement is much harder

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

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

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

  • 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

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

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

    • block title?

  • 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

    • allow line height to be set in more places (such as the prose for admonition, example, sidebar, etc)

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

    • option to not indent first paragraph in section

    • add indent/noindent options

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

  • add entry to TOC for preamble/preface

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

    • would need to override how blocks join content; perhaps even how apply_subs works

  • don’t issue warnings on scratch document

    • perhaps introduce a helper method to abstract this away

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

    • no longer a problem? perhaps was due to #462; could also be when it does wrap by char

  • 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 (#571)

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

    • need to find a good cover page

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

    • implement orphan sentences for paragraph

  • fail gracefully if theme file cannot be found

    • report it can’t be found (should we fallback to default theme?)

  • expose theme variable on document (using attr_reader?)

  • 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

  • subtitles for parts and chapters (#623)

  • part titles need their own 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 why we have converter assignment in convert_content_for_block method

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

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

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

  • 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)

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

  • strip formatted text (e.g., monospace) from headings and 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; fixed?

  • 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)

    • perhaps 4-sided border?

  • 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

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

  • CJK and/or multilingual support (see https://github.com/chloerei/asciidoctor-pdf-cjk)

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

  • allow font properties to be set for lists (description_list, outline_list)

  • remove pdfmarks file after optimizing

  • 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)

  • create proper default (Asciidoctor) theme (#60)

  • document how the treetop parser is rebuilt

  • 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

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

  • honor safe mode rules

  • 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)

  • 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?)

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

  • 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 font color (and family?) in headings

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

  • implement quote style from default Asciidoctor stylesheet

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

  • rename "theme" to "style"? (or allow both?)

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

  • enforce jail on SVG option enable_file_requests_with_root

  • implement convert_toc

  • 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")

  • 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

    • still true?

    • I believe we patch by calling update_colors if graphic_state.color_space.empty?

  • add /PageMode /UseOutlines

  • cli arguments

    • theme (pdf-style, pdf-stylesdir)

    • enable/disable writing pdfmark file

    • optimize-pdf

  • implement footnotes correctly (#73, #85)

  • flesh out outline more (in what way?)

  • flesh out title page more

    • document subtitle (partially solved)

  • don’t create title page for article doctype (#95, #105)

    • only create title page if doctype=book

  • allow character spacing to be controlled by theme

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

    • intended primarily for image slideshows

    • this is slighly more complicated now that we have mirror margins; perhaps can’t set those from document?

  • use module Asciidoctor; module PDF; module FormattedText convention to simplify indentation

  • introduce code style guide (like in Jekyll AsciiDoc); perhaps make this a shared file in the Asciidoctor ecosystem?

  • I’d like for theme to be able to set font scan path for Prawn SVG, but registry is global

  • rename dot_leader to just leader or tab_leader?

  • rename align to text_align?

  • QUESTION should bullets be on right if list alignment is right (what about center?)

  • QUESTION should we resolve font-based icons globally, in init_pdf?

  • use treetop to parse and evaluate theme file

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

  • switch wolpertinger to howling grasshopper mouse

Major Efforts / Milestones

  • add a test suite

  • refactor as Prawn View

  • add support for footnotes (as article or chapter endnotes)

  • pass styles downwards to child elements in formatted text transform instead of decorating on way out of hierarchy

  • rework text handling in Prawn to support line height natively

  • margin collapsing (like CSS)

  • use proper model to handle the page number to current part/chapter/section mapping in running content

  • cleanup/reorganize imports in lib/asciidoctor/converter.rb

Documentation

  • "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

Questions

  • should we calculate column widths before cell data so we can pass width to AsciiDoc table cell?

  • should we ensure natural_content_width is called first (by calling it explicitly)?

    • seems by calling width on table in convert_table, this isn’t necessary

  • should width for AsciiDoc cell when autowidth is set default to even distribution (accounting for colspan?)

Notes

  • when using single_line: true on formatted_text, it’s necessary to reapply our padding top/bottom from line metrics

  • we always leave cursor on start of page we’re about to write on; certain checks rely on this fact

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

  • /PageLabels/Nums must have entry for every page in front matter, even if a blank page

    • in fact, must account for every page or else numbering lags behind when scrolling document

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

  • any instance variables referenced by converter methods for inline nodes could get accessed before the converter for document is called

  • Evince throws warning when printing PDF if & is used in document title; but this is valid according to the PDF specification

  • Prawn drops fragments with empty text (hence the need to use zero-width space)

    • analyze_glyphs_for_fallback_font_support drops fragments with empty text

    • later on, initialize_wrap drops fragment with empty text

  • use term "page number label" to refer to the visible, printed page number (not the implicit page number)

  • vertical alignment of text doesn’t work properly in Prawn; better to calculate alignment manually, if possible

  • width_of_string returns a value from the font horizontal metrics map even if glyph is not present in font

  • check for AFM font using: theme_font :link { font.unicode? }

Snippets

Report error eagerly if can’t read image in running content:

warn %(asciidoctor: WARNING: could not embed image in running content: #{path}; #{e.message})
side_content[position] = %([#{attrs['alt'] || (::File.basename path, (::File.extname path)).tr('_-', ' ')}]

Prawn Wishlist

  • fragment should be able to specify it’s own width

  • test string with include? before gsub (for example, stripping zero-width spaces)

Known Issues

  • when paragraph text runs to another page, all zero-width spaces and soft hyphens have been removed from the text; this means word breaks don’t work and callbacks for placeholder text aren’t called

  • inline image at start of the line is slighly shifted to the right due to the fact that it’s placed in the center of the reserved fragment width; perhaps we are adding this padding

Potential Optimizations

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

  • comparing > 0 is slightly faster than == 0 (for cases when we can swap the logic)

  • could define rx constants on demand, such as:

    self.class.const_set :UriSchemeBoundaryRx, /(?<=:\/\/)/ unless self.class.const_defined? :UriSchemeBoundaryRx, false

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

Implementation

  • should we read SVG file using UTF-8 encoding; or does REXML handle encoding?

  • can we leverage before_rendering_page callback on table?

  • should we use move_past_bottom in some places instead of start_new_page?

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)