thomasauriel / html-handbook Goto Github PK

A HTML Handbook

JavaScript 86.71% Java 10.92% HTML 0.03% CSS 2.34% Shell 0.01%

json javascript java html-handbook mathjax firefox handbook html asciimath mathml

html-handbook's Introduction

HTML Handbook

HTML Handbook is a way to organise notes inside handbooks. Notes are linked together through tags. All notes are aggregated in a unique vertical column allowing to display and print it similarly to a true handbook.

From Github to Gitlab

The project moved to https://gitlab.com/ThomasAuriel/HTML-Handbook

Version

Version 0.5

The version 0.5 reworks the Java code to optimise it (faster and easier to support).

The user will not see large changes. The modification noticeable are:

General structure of the final handbook.
Easier CSS edition
Faster compilation
More explicit error messages

Version 0.4

The version 0.4 uses the markdown syntaxe to write content. The version is simpler than all previous versions thank to a large rework on data structure. This version is also a lot of lighter. The new version is only 38MB compare to the monstrous 172MB of the previous versions. You can still reduce the size by removing MathJax. Its only purpose is to render math equations. See documentation

Motivation

I created this tool since I was not able to find a similar and simple method to show information. There are different interesting tools as wikis (such as TiddlyWiki or Zim). However, the information is displayed by elements and not in a stream. The stream view allows to move around those elements without following a precise path and find easier information (in addition of tag navigation).

The first is a Latex template associated to scripts to compile and load automatically content. I appreciate it since it is easy to use it. But it requires a Latex compiler.

This second tools need only a Firefox browser. Using only Firefox as renderer software makes this tool cross-platform and portable. I did not develop this tool for other browser since they have limitations access to local files. To produce the final handbook Java 1.5 or higher should be used. Today, Java 1.8 is public and most computer can run Java 1.5 code without issue.

How to Use

I provide documentation in the sources. Since this documentation use the tool, it is also a complete example.

Tips

Use only ASCII characters in the folder and file names (no special characters). Otherwise, the handbook could be loaded incorectly. Do the same for ID tags.
To be able to write and use mathematical equation, please unzip MathJax from its zip in ./js .

html-handbook's People

Contributors

Stargazers

Watchers

html-handbook's Issues

Empty tag list include all elements bellow it

Similar to #2

Previous tasks are not correctly handled

If in the previous task list an id refere to not tasks (typically due to an typing error), an exception is thrown and display.
The issue is that the exception message is 'null'. It should be more explicite or the link to the previous task should be similar to the tag system.

Sub-elements of list are not correctly handle

The following example is not correctly rendered:

1. This an element of a list.
  This is the same element of the list. (1)
2. This is a second element of a list.

The line (1) is not considered in the list but it should.

Does not manage Zip files

The tool try to interpret zip file as Markdown files.
This result in an error during the execution.

The path to the image representing file path is not correct.

The image path in the jar shall be changed from ./css/file.svg to ./handbook-config/css/file.svg

Empty toc include all next elements.

The toc tags (and ul tags) include all the next elements present in the document.
To avoid this behaviour they should be include only if they contain already sub element.

Impossible to use the id "-"

Impossible to use the id "-".

Does not keep the XML properties defined in templates

The XML elements in templates can contains properties. This properties can be usefull for CSS or other. The generation shall keep them.

Does not handle correctly windows encoding

The encoding is not correctly handle. So the formatedHandbook file contain misspell words.

Issue in the path of images to display

Images are not correctly displayed when they are stored localy.
The function image does not provide the correct pass in the final handbook.

Reorganize the folder structure

The new folder structure shall be similar to

rootFolder +
                 + handbook-folder +
                                                + css
                                                + js
                                                + jar
                                                + etc ...
                 + handbook.md
                 + notes +
                              + note1.md
                              + note2.md

All the files to run the handbook shall be hidden in the handbook-folderand does not need to be at the root level.

MathJax is too large

The MathJax javascript library, used to render equations, is too large and has too many files.
It is necessary to reduce them to the only useful files.