path: root/WORKLOG.adoc

= WORKLOG

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

== TODO

* document show-link-uri in table on asciidoctor.org

* 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

* examine uses of attr/attr? and ensure we only inherit when desired
* submit pastie theme for Rouge upstream
* log warning with reason when remote image can't be read
* 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?)?
* document missing keys in theming guide for 1.5.0.beta.1
  - missing text_transform in some places
* support the reversed option on ordered lists (see https://github.com/asciidoctor/asciidoctor/issues/1830)
* 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?
* enable/implement key table_font_style
* allow style of visible link to be controlled by theme
* check that color of table edges set to table_grid_color??
* shouldn't the default align for headings be $base_align??
* should not wrap at formatting mark unless it is at a break opportunity
* rename :entity to :charref in text parser
* 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., [[:word:]] 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 (or ThemeManager)?
* 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
  - is this always the case?
* normalize step leaves space after endline (i.e., `\n `) at a hard line break (doesn't seem to affect flow)

* *margin per heading level* (see https://github.com/asciidoctor/asciidoctor-pdf/issues/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 https://github.com/prawnpdf/prawn/issues/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)
  - 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
* 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

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