Commit b27107ad authored by Baptiste Perraud's avatar Baptiste Perraud

Update README

parent 5f7f42df
...@@ -43,7 +43,7 @@ Use this method if you do not want to use a terminal. ...@@ -43,7 +43,7 @@ Use this method if you do not want to use a terminal.
#### Terminal: #### Terminal:
By using the terminal you can specify some parameters to the conversion at the moment: the source file. By using the terminal you can specify one parameter to the conversion at the moment: the source file.
1. Download hdoc_converter.zip and unzip it. 1. Download hdoc_converter.zip and unzip it.
2. Open your terminal and go into the folder hdoc_to_pdf. 2. Open your terminal and go into the folder hdoc_to_pdf.
...@@ -55,37 +55,41 @@ By using the terminal you can specify some parameters to the conversion at the m ...@@ -55,37 +55,41 @@ By using the terminal you can specify some parameters to the conversion at the m
Use -DInputFile to specify the source file. Use -DInputFile to specify the source file.
Exemple: Exemple:
"ant -buildfile hdoc_to_optim.ant -DInputFile=sample.hdoc" "ant -buildfile hdoc_to_pdf.ant -DInputFile=sample.hdoc"
This parameter is optional. Your file has been converted, the result is in the output folder. This parameter is optional. Your file has been converted, the result is in the output folder.
Flying Saucer limitations
-------------------------
* Nested ul in ol are sometimes converted to ol... [only noticed once, to be verified]
* It seems that FS doesn't support the max-width or max-height for img tags, which makes proper scaling harder... For now, as a temporary solution, we scale all images at a width of 80mm.
* ToC lines rendering is sometimes ugly if the title label is too long: dotted leader or even page number may appear on the following line, sometimes colliding between themselves.
* Inline elements like em cause bad paragraphs justification if they are rendered at the beginning of a new line.
* FS doesn't support the CSS widows/orphans properties, which makes their handling harder.
Known bugs Known bugs
---------- ----------
* Nested ul in ol are sometimes converted to ol. * Sometimes, they are still unwanted page breaks before a heading + list (e.g. h4 then ol).
* It seems that FS doesn't support the max-width for img tags, which makes proper scaling harder. * A schema validation is executed by jing during the hdoc_to_pdf conversion. Normally, if the validation fails, the process should abort because we are not treating a valid hdoc file. However, at the moment, the script only warns the user of the error and goes on, because the schemas and the opale_to_hdoc converter are not synchronized at the moment (it needs to be corrected).
* ToC lines rendering is sometimes ugly if the title label is too long: dotted leader or even page number may appear on the following line, sometimes colliding between themselves.
* Inline elements like em cause bad paragraphs justification.
* Sometimes, they are unwanted page breaks after a heading.
Generic Todo Generic Todo
------------ ------------
* Generate a clean PDF file (using the LaTeX formatting example) * Rework the hdoc_to_pdf.ant and find_content.xsl scripts to allow multifiles handling.
- Create a default CSS file with basic spine rules * Handle as fully as possible of widows and girl orphans; trying to match Prince's layout and implementing the suitable CSS rules (which shall not be interpreted by FS).
- Get the right free font (equivalent to the LaTeX's one) * Allow the user to override some specific CSS rules, according to the main layout logical rules.
* Generate the ToC according to the converted (by XSL) headings of the hdoc * Provide the user with a full set of options/parameters to customise the output: bound/unbound, odd/even margins, report/article LaTeX format (first page formating), etc.
* Handle as fully as possible of widows and girl orphans; trying to match Prince's layout and implementing the suitable CSS rules (which shall not be interpreted by FS) * Bonus: find out a HTML editor to manually add line breaks to a hdoc file in order to resolve widows and girl orphans problems after the PDF file's generation.
* Allow the user to override some specific CSS rules, according to the main layout logical rules
* Manage container.xml and content.xml validations using jing as jing task can't be handled with opale_to_pdf.ant call.
* Bonus: find out a HTML editor to manually add line breaks to a hdoc file in order to resolve widows and girl orphans problems after the PDF file's generation
Specific Todo list Specific Todo list
------------------ ------------------
* Gestion du bug d'espace qui apparaît après un lien.
* Ajouter le paramètre de reliure ("bound") au script ant * Ajouter le paramètre de reliure ("bound") au script ant
* Intégrer les styles CSS selon le paramètre "bound" dans un xsl * Intégrer les styles CSS selon le paramètre "bound" dans un xsl
* Ajouter le paramètre de recto-verso au script ant * Ajouter le paramètre de recto-verso au script ant
...@@ -107,6 +111,7 @@ Technical notes ...@@ -107,6 +111,7 @@ Technical notes
--------------- ---------------
* This converter works with _only one_ hdoc file in the input folder at the moment, please ensure to clean the folder before proceeding with the hdoc you want to convert to PDF. When the multifiles ability is set within the hdoc_to_pdf converter, the opale_to_pdf one shall naturally work because it already implements the opale_to_hdoc multifiles handling (the copy of all the hdoc results into the input directory of the hdoc_to_pdf converter). * This converter works with _only one_ hdoc file in the input folder at the moment, please ensure to clean the folder before proceeding with the hdoc you want to convert to PDF. When the multifiles ability is set within the hdoc_to_pdf converter, the opale_to_pdf one shall naturally work because it already implements the opale_to_hdoc multifiles handling (the copy of all the hdoc results into the input directory of the hdoc_to_pdf converter).
* The java classes we use for the project are located in the "lib/MyPDFGenerator Sources" folder, please modify these if needed before compiling and adding the new jar file to the lib folder. In Eclipse, when the class is modified and ready to be exported, please choose the "Runnable jar file" export option.
User Story User Story
---------- ----------
...@@ -121,3 +126,7 @@ User Story ...@@ -121,3 +126,7 @@ User Story
Capitalisation Capitalisation
-------------- --------------
* A16 : during this semester, we have built a hdoc_to_pdf converter from scratch, which aims to be integrated in the global hdoc project. We use the java library Flying Saucer (FS) for the purpose, but this tool has some limitations, the ones we have already noticed are listed above.
At the moment, the converter is functional and deals with main PDF layout properties: title and authors, pages numbering, headings ranks, ToC generationk, basic inline formating (+ fonts) and nested lists for instance. Some elements still need to be worked on, especially the widows/orphans behaviours for the lists. Other elements need to be handled, like the tabulars or specific objects (e.g. odg resources).
The main objective has been to keep whenever it is possible the right formating and typographic rules (often in comparison to the LateX ones), and thus deliver a readable printed document at the end.
...@@ -44,6 +44,8 @@ Follow the steps above to get a pdf file from a scar one: ...@@ -44,6 +44,8 @@ Follow the steps above to get a pdf file from a scar one:
4. On Linux or Mac, run the script run.sh. On Windows, run the script run.bat. 4. On Linux or Mac, run the script run.sh. On Windows, run the script run.bat.
5. Your file has been converted, the result is in the output folder. 5. Your file has been converted, the result is in the output folder.
**Warning: on Windows systems, the script may fail due to the lack of writing rights for some folders, try to re-execute it once are twice and it should work (until this bug is solved).**
Unsupported Unsupported
----------- -----------
...@@ -53,6 +55,8 @@ Refer to the unsupported elements in Opale to Hdoc and in Hdoc to Pdf. ...@@ -53,6 +55,8 @@ Refer to the unsupported elements in Opale to Hdoc and in Hdoc to Pdf.
Known bugs Known bugs
---------- ----------
- The windows execution of the run.bat script sometimes fails (problems when we try to remove some folders).
Refer to the known bugs in Opale to Hdoc and in Hdoc to Pdf. Refer to the known bugs in Opale to Hdoc and in Hdoc to Pdf.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment