phrogz / docubot Goto Github PK

A simple project like this:

Hello World.md
_static
  images
    foo.jpg

ends up creating a TOC like:

Hello World
images

Just as files inside _static should be ignored, so directories therein should be ignored.

Put HTML id attributes on headings, definitions, fieldset labels, and table captions if they don't already have them. Modify the toc: ... walker to allow quoted sections referring to the titles. Use the same text-to-id algorithm for both, and voila! Markdown will work fine for pages with sub-anchors needed.

The project has become sufficiently complex that it's hard to know if any change will break other code. Must get some specs and test files up ASAP.

It's annoying to have to write href="../../../foo/bar/page.html", and fragile.

Worse, however, is that you can't have a single Glossary entry re-used on different pages in the site that links to another page discussing it in detail.

Simple would be some sort of special href="#{root}/foo/bar/page.html" syntax that properly substituted root even in templates that didn't have Ruby interpolation.

Even better would be an addressing system that found a page based on its title (or better yet, some magic internal GUID-like thing) so that the user could rename the page or put it in another directory without all links to it breaking.

Integrate the output of Doxygen, or something.

Like Bundle#validate_links, look in src attributes of images and validate that the files are there (unless sourced over another protocol). Possibly extend to scripts, too. Add command-line options and Bundle creation options to skip these steps.

Don't validate stylesheets, because they shouldn't be in the page body anyhow.

When a page has a meta section like:
toc: sections
have the bundle find—and if necessary, add unique IDs to—every header in the page and create TOC sub-entries for them.

TBD: Where does TOC logic belong? Currently it's implicit in the hierarchy of Pages; perhaps we have a new DocuBot::SubSection that lives as a child of the Pages with a similar interface?

Use SinglePageHTMLWriter and then generate a PDF

Instead of generating a Glossary section, generate a proper (custom) Glossary tab in the sidebar of the CHM, as described here.

Because Sphinx has it. Minor problem: missing a nice cross-platform pure-Ruby converter.

• toc.haml links in glossary.js and glossary-terms.js and glossary.css.
• HTMLWriter creates glossary-terms.js with every term/definitionHTML pair from the Glossary after crawling.
• glossary.js finds all <span class="glossary"> on the page and hooks up interaction to show the definition of the term on click.
• glossary.css is separate from nvdevtools.css and puts unique style on glossary terms (e.g. dashed underline).

Why does the CHMWriter have its own directory for ERB files in lib/docubot/writers, but the HTMLWriter uses hamls from lib/docubot/templates/default?

• Allow users to create relative HTML links to the original (markdown/textile/whatever) files in the source.
• During write, after generating HTML for pages, use a map between the original file path and output html path to munge <a href="..." links to point to the correct relative file path.

A textile document with a mailto: link shows a warning for "broken link" during conversion.

For HTML-only output, create an index.html that has a frameset pulling together toc/index and content. (This includes a nice tabbed approach for a nice toc/index display.)

Parse the structure of the final page HTML and wrap <div class="section">...</div> around the contents of each logical section (determined by headings, up until the next heading of equal or greater priority).

Allows simple CSS like .section { margin-left:2em } for clean indentation of page structure.

Currently every page upon creation generates IDs for a host of elements (if not present). The only reason this is used (currently) is for the TOC linking in comma-delimited mode. Perhaps it'd be better to go and find the elements with the requested TOC entry and just auto-id them. If a page doesn't have a toc metaattribute, or the metaattribute doesn't have commas, skip the auto-id altogether.

There is one problem with trying to exactly auto-id only the referenced elements.The following textile code:
h2. What's Up
generates a curly quote entity for the apostrophe in the process of creating the HTML. As a result, a straight text match for "What's Up" would fail on the HTML.

The index should be able to have entries like:

Rigid Bodies
   Basics
   Creating
   Rigid Body Modifier

Presumably this would only be through a meta entry—using some TBD syntax—and not through the auto scanner.

When writing HTML, look through the HTML and see if there are any relative links that are broken.

• Detect lack of hhc.exe in path early on and bail with helpful instructions for downloading it and setting the PATH.
• Perhaps go hunting for it in the standard spots and call it directly without PATH modification.

When scanning headings and definitions for index entries, record with the page the link to the actual heading where the term exists.

Allow Word 2007 documents as page sources, converting the .docx to HTML, extracting the body, and cleaning the result through markup sanitization and/or CSS to override foolishness.

OpenXMLViewer is one possibility for command-line conversion.

Textile markup like This is an @@indexable@@ term generates <code>@indexable@</code> in Textile, causing incorrect output and the index snippet to fail.

The simplest, best solution is to process snippets before converters; just need to ensure this works.
Alternatively, we could come up with a different, non-conflicting markup for snippets.

http://doc.trolltech.com/3.3/assistant-6.html
http://pepper.troll.no/s60prereleases/doc/assistant-custom-help-viewer.html

New writer that puts the entire document in a single HTMLPage.