Moved the ReplicadManual to the wiki

[raydeleu]

For some time I tried to create a kind of manual for Replicad that provides a little bit more information than the documentation provided at www.replicad.xyz. I used the git repository https://github.com/raydeleu/ReplicadManual for this purpose. As the document became quite long for a single file, I experimented with using the wiki at the same site https://github.com/raydeleu/ReplicadManual/wiki. The conversion is still not complete, but the wiki already contains more information than the "readme.adoc" at the main repository. The work in progress can be found in a subfolder of the code part https://github.com/raydeleu/ReplicadManual/tree/main/wiki. When a chapter is more or less readable, I copy the result to the wiki for publication.

I hope you like it. Feedback and ideas for improvement are welcome.

[sgenoud]

I still really want to help you setup your manual as a website (but still have not found the time to actually do it). With your conversion to markdown this will be even easier to make something nice (and simple).

That said, have you found a way to export the wiki as a pdf?

[raydeleu]

The long "readme.adoc" became more and more a burden so I decided to split up the document. Unfortunately Github does not support the include statement of Asciidoc, so I could not achieve what I intended. Therefore I decided to try the approach of using the wiki.

With the move from Asciidoc to Markdown I had to accept that captions and numbering of illustrations is difficult to achieve (or can be done only manually), that section numbers in the wiki can not be automated and that creating a pdf is also difficult. The solution that I hope to achieve is to create the files for the wiki in the code section of github first. This allows me to download a zip-file with all the contents to my own computer. Then I hope to use Pandoc to concatenate all files and convert these to a big html file that I can print using the Chrome browser, or to a Word document that I can convert to a pdf of using LaTeX to produce a pdf. I have used pandoc in the past so I think I should be able to reach a workable solution. It is far more work than just pushing an asciidoc through a Chrome extension and print, but the reward is an improved structure and better maintainability throughout.

Currently I am still a bit struggling with cross-references/hyperlinks between chapters. My assumption is that pandoc will handle it fine as I understood that when feeding a list of files to pandoc, these are automatically concatenated to a large file again before the conversion. Within the wiki it might be different, I have not figured that out.

Then I will have a look whether I can use pandoc to number illustrations without breaking the wiki syntax. It seems that pandoc can support cross references but that I then would have to convert the files first before copying the result to the wiki-section. For now I still have to do a lot of editing, converting asciidoc to markdown et cetera, so the whole process will take some time ...

Edit: I already ran into the issue that the pandoc conversion to Word seems unable to handle the html-tags for images that I use in the Github wiki. The Markdown image syntax in Github on the other hand does not allow to set the width of images. It is a tricky set of problems that I thought I had solved with asciidoc ...