path: root/WORKLOG.adoc

= WORKLOG

* use Groovy language specification as case study to find corner cases
  - perhaps progit2 as well; others?

== TODO

* convert image width to points for images on title page and in running header and footer; add support for pdfwidth
* upgrade Treetop
* recognize inline image syntax in page_background_image key
* allow front cover and back cover image to be defined in theme; document in theming-guide
* 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)

* rewrite optimize-pdf using rghost
  - add Optimizer class; wire to cli
* layout SVG without using keep_together (since we know all the dimensions)
* pass macro doesn't work in source block when macro subs and highlighting are both enabled
* bind image_registry between scratch and main document so we don't process the same image more than once
  - need to do some testing
* 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)
* margin per heading level (see https://github.com/asciidoctor/asciidoctor-pdf/issues/176)
* 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?)
* 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?)
* 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
* support generic color (or value) attribute in formatted text parser instead of specific color systems (rgb, cmyk)
* file issue to import PDF page using block image macro
  - add pdf page import support to the image block macro (file issue)
* **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)
* 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)
  - fix the background color mess in convert_table
  - extract regex in ThemeLoader into constant
  - remove dead code dealing with margins
  - decide how we want to format theme_loader.rb (should be consistent)
  - 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 https://github.com/prawnpdf/prawn/issues/802)
* make CodeRay theme colors configurable (in theme?)
* 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
* use padding from theme around admonition block content
* use padding from theme around block quote content
* add admonition_label_font_color to theme
* remove remaining uses of vertical_rhythm and horizontal_rhythm
* 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)
  - 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)
* print scratch.pdf file if verbose / trace mode is on in Asciidoctor
* introduce setting to indent section content
* design merge margin logic (like for admonition block)
* 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
* image border
* 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

== 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
* avoid the fallback font if possible (use full fonts in your theme)
* 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)

== 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]