= WORKLOG

== TODO

* 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 https://github.com/asciidoctor/asciidoctor-pdf/issues/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
 ** see https://github.com/asciidoctor/asciidoctor/pull/2286
* 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
 ** see https://github.com/mogest/prawn-svg/issues/96
* Prawn reports unknown blank font if family is valid but style is invalid (see https://github.com/prawnpdf/prawn/issues/1022)
* catch UnsupportedImageType and issue warning that suggests using prawn-gmagick; see sandbox/interlaced.png
* something like prawn-gmagick in Java env
 ** look into https://github.com/jcupitt/ruby-vips for faster image processing (might solve our JRuby issue)
* 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 https://github.com/jneen/rouge/issues/665)
* FIXME: stop using fallback fonts in default theme (instead, bundle a fuller font)
 ** using fallback fonts significantly slows down Prawn because it checks every letter every time (see https://github.com/prawnpdf/prawn/blob/master/lib/prawn/text/formatted/box.rb#L427-L434)
 ** 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
* 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; https://github.com/prawnpdf/ttfunk/issues/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 https://github.com/prawnpdf/prawn/issues/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: http://asciidoctor.org[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
 .. in dry run, set to stop when advancing to next page (override on_page_create to throw exception)
 .. if less than one page, return calculation (similar to what we do now)
 .. if greater than one page, clear on_page_create; move to y offset of original and start dry run again; fix calculation
 .. (if not keeping together, we can skip 1 and 2)
 .. 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: https://github.com/prawnpdf/prawn/issues/951 and https://github.com/prawnpdf/prawn/issues/473
* document how to test / use a PR
 ** see https://github.com/asciidoctor/asciidoctor-pdf/issues/462#issuecomment-246200953 (Bundler)
 ** also see https://github.com/asciidoctor/asciidoctor-pdf/issues/650 (Gradle)
 ** clearer instructions for how to test local development version (using rake install)
* 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 https://github.com/prawnpdf/prawn-table/issues/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., [[:word:]] 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 https://github.com/prawnpdf/prawn/issues/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 -> ﬁ); 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)

== Resources

* https://code.google.com/p/origami-pdf/[Origami PDF: A PDF inspection library]
* https://github.com/a1ee9b/PrintPretty[A theme for PDF designed for printing]
* http://randomtextgenerator.com[Random Text Generator, supports multiple languages]
* http://clagnut.com/blog/2380[List of pangrams]
 ** http://www.camcc.org/_media/reading-group/qianziwen-en.pdf[1,000 character classic (Chinese)]
* pdf2svg can convert the PDF file into an SVG (one SVG per page)
* https://blog.codeship.com/build-math-evaluation-engine[How to Build a Simple Math Evaluation Engine]
* http://blog.typekit.com/2011/11/03/optimizing-fonts-for-the-web-unicode-values-glyph-set-underlines-and-strike-through/[Optimizing Fonts for the Web]
