- Fixed display bug on generated documentation.
2010-03-08
2010-03-03
HTML default stylesheet improvements
A new default HTML stylesheet will be available soon. It should improve Novelang usability a lot. Key features are:
- A better look.
- Scaling up with metadata-oriented features.
If a picture is worth a thousand words:
Fluid layout
New layout supports horizontal resize. The column for rendered text may span from 500 to 1000 pixels.
Lines of literal (<pre> tag) wrap if they are too long. Because wrapping only occurs with the white-space : pre-line style, which discards indentation by default. To prevent this, some JavaScript replaces every space character inside a <pre> by a non-brekable space, immediately followed by a zero-width space. This causes a clean-looking wrapping, but text copied in the clipboard has unwanted character.
Overall look
Titles are indented. This is a compromise with the Descriptor feature (described later).
Line spacing is constant, even between two paragraphs, or between a paragraph and an embedded list. There is a slight loss of information (it may be hard to see where a paragraph begins) but this globally increases readability.
Fonts
Font choice has a huge impact on overall look. Chosing fonts is hard stuff, because fonts rendering is hardly the same across Web browsers. Font readability also changes a lot, depending on line spacing, contrast, and other fonts around.
The convention is: serif font for rendered document, sans-serif for extra information like actions and tags. Literal (<pre> and <code>) shows with a fixed-with font, which is serif, too.
After experimenting with a lot of combinations, finally, the winners are:
— Palatino Linotye for the rendered document. This gorgeous font is a bit more readable than Times New Roman. It’s available on all platform, and looks gorgeous with appropriate contrats (dark grey over light gray instead of black over white).
— Lucida Grande with Tahoma as second choice. Lucida Grande is highly readable (was chosen as default for Mac OS X), but sophisticated enough to not look “poor” aside Palatino.
— Courier New is not new at all, but it mixes harmoniously across text in Palatino. Those fonts display much better on Mac OS X, or with Safari on Windows XP.
Descriptors
Descriptors appeared in Novelang-0.39.0, as an experimental feature. They now display with a nice fade and animation, in order to preserve user’s visual landmarks. Descriptor have a vertical bar that helps to see the scope of the descriptor. This vertical bar only shows when Descriptor is discloed.
Descriptor disclosers now appear close to Tag column. This avoids polluting the left margin.
Scalable lists for metadata
On big documents, there can be so many tags they don’t fit in the height on a Web browser’s window. But most of time, they all fit so it’s convenient to have all of them at a fixed position. How to deal with the exception without hurting common case? Having a 2nd scrollbar in a browser’s frame looks confusing. But the scrollbar has a great feature: it shows that some items are out of sight. One trick could be displaying a huge popup, but this probably means a lot of work for a poor result.
Finally, the solution comes with a fade to grey at the end of the list to show that all items don’t show. A tiny button “unpins” the tag list from the top of Web browser’s window and lets it go to the document’s beginning. So, when entering the “1 % case” we still have a standard behavior.
Here is the Tag tab in its default pinned state (note the fade at the bottom and scrollbar position):
Unpinning causes it to scroll with the rest of the document:
In addition to Tags, there will be, in a (hopefully near) future, more metadata like Identifiers. Tags show up under a tab bar where it’s easy to add new tabs.
2010-02-21
Novelang-0.39.2 released!
Download Novelang-0.39.2 here !
- Reject diacritics in tags.
- Filter on implicit tags as on explicit tags.
2010-02-17
Novelang-0.39.0 released!
Download Novelang-0.39.0 here !
- Experimental feature: descriptors in default HTML stylesheet.
- Support Unicode files starting with a BOM (Byte Order Mark).
- Reject TAB character.
- Display Unicode name of a rejected character (as long as it belongs to the set of 16 bit Unicode characters as defined in Unicode 5.2 standard). This feature is experimental and may wreck existing error messages.
2009-12-27
Descriptors in HTML
Designators are identifiers and tags. Source document may contain explicit designators, but since version 0.37.0 Novelang is smart enough to generate implicit designators from the text of source documents. Rules for implicit designators are as intuitive as possible, but it is helpful to show somewhere the implicit designators Novelang generated for you.
So default HTML stylesheet introduce a new artefact called “descriptor”. It’s a text area surrounding a paragraph or a level title, that unfolds for displaying implicit descriptors and maybe other useful things in the future, like location in the source document.
Looks like this:
The descriptor shows:
- Implicit identifier:
\\ThisIsASectionWithATitle_andStyleInsideTheTitle - Implicit tag:
ThisIsASectionWithATitle - Implicit tag:
andStyleInsideTheTitle
While working on layout and animation I found those links useful:
JQuery , the must-have JavaScript framework for doing everything with browser’s DOM in an concise and elegant fashion.
Stuff About CSS floats. (As a bonus, found this one about floatless layout , may become useful one day.)
CSS popups are fine but I gave up this way as the popup only appears with mouse pointer over a drop zone, prevents from copy-pasting.
This one about null HTML links also helped to drop bad ideas.
2009-12-22
2009-12-21
2009-12-14
Generating human-friendly designators
A Designator helps to locate text fragments. This is a generic term for Tags and Identifiers. With Novelang-0.37.0 come Implicit Identifiers, that make a level title behave as an Identifier. With explicit Identifiers, to reference a level from an insert command you decorate the level with an Identifier like this:
\\Preamble == Preamble This is a preamble, blah blah blah...
And this is how to insert only the Part with “Preamble” title in some Novelang book:
insert file:my-document.nlp \\Preamble
But why duplicating the “Preamble” word? As long it doesn’t collide with another Identifier we should be able to write:
== Preamble This is a preamble, blah blah blah...
… And use the insert command the same way.
Now with this feature available, it makes sense to support implicit Tags, too. When requesting a document containing only fragments tagged with @Preamble one could expect to see our level with “Preamble” title. The need for Implicit Tags and Identifier came out from documents looking like this:
\\Preamble @Preamble == Preamble ...
Quite not good, for a typing-savvy tool, is it? So now we need a common rule to create Implicit Tags and Implicit Identifiers out from legal Novelang level titles.
There are some differences between Implicit Tags and Implicit Identifiers.
— Implicit Tags don’t appear in the list of explicitely-defined Tags (in the n:meta/n:tags element).
— One given level title generates only one Implicit Identifier, but it may generate several Implicit Tags. This makes sense for long titles; the longer they are the less likely they are to appear several times in the rendered document. With a simple rule – like breaking on punctuation signs – a long title may generate several meaningful Tags.
Here are some generic rules for crafting Implicit Designators:
— Generate something as close as possible of what a human could write.
— Resolve to a limited set of characters that comply with the specification of a URL . By now, Tags appear in the URL-like document request as parameters. There is a chance to support Identifiers as document request parameters, too.
To make a long story short, the RFC lists diacriticless letters, digits and "$-_.+!*'()," characters as legal part of a URL. We can note there is non-uniform support of punctuation signs (! supported but not ? and :). For this reason, we exclude punctuation signs. Same for paired delimiters. The asterisk, plus sign, and dollar sign don’t appear as document construct (they may only appear under some escaped form), so we exclude them too. Only remain low line _ and hyphen minus -.
Implicit Tags split on punctuation signs, while Implicit Identifiers must keep them by some mean. By disallowing the low line in Tag syntax, we save it for punctuation sign replacement for Implicit Identifiers.
The hyphen minus may replace space character. But forcing character case to camel case makes shorter Designators, while keeping them quite readable. Camel case only happens for whitespace stripping between two adjacent words.
Samples:
Document source Implicit Designator aéœ aeoe x, yz x_yz -> 2 Tags: @x @yz X, yz X_yz -> 2 Tags: @X @yz v `0.1.2` v0-1-2 Foo bar FooBar foo bar fooBar foO BAR foOBAR w (x yz) w_xYz -> 3 Tags: @w @x @yz
2009-12-13
Novelang-0.37.0 released!
Download Novelang-0.37.0 here !
- Implicit identifiers, deduced from level’s title. See “Identifiers” chapter in Part syntax.
2009-09-27
Novelang-0.36.0 released!
Download Novelang-0.36.0 here !
- New
--style-dirscommand line parameter (superceding--style-dir) for multiple style directories.
- Minor identifier-related fixes and internal refactorings.
2009-09-20
Novelang-0.35.0 released!
Download Novelang-0.35.0 here !
- Experimental support for identifiers. See “Identifiers” chapter in Part syntax, and “Insert Command” in “Book Files”.
2009-09-09
Novelang-0.34.1 released!
Download Novelang-0.34.1 here !
- Fixed: bug preventing from starting a Novelang release with a numbered version.
Novelang-0.34.0 released!
Download Novelang-0.34.0 here !
- New
levelaboveoption forinsertbook command.
- New
sortoption forinsertbook command.
- New
explodelevelbatch command for splitting one document’s levels into several parts.
- New
--content-rootcommand line argument for setting the directory where content files reside.
- Fixed: paragraph as list did not support indented embedded list items.
2009-08-23
Novelang-0.33.1 released!
A new release of Novelang is available! Download it here and see documentation for details.
2009-08-21
2009-08-17
Novelang-0.33.0 released!
A new release of Novelang is available! Download it here and see documentation for details.
2009-08-08
Novelang-0.32.1 released!
A new release of Novelang is available! Download it here and see documentation for details.
2009-08-02
Novelang-0.32.0 released!
A new release of Novelang is available! Download it here and see documentation for details.
Subscribe to:
Posts (Atom)