Generate a New Toc.md (is there an automatic way to do it?)

[carlosdelfino]

I'm starting the update file toc.pt.md but realized that manually is a tiresome job, and what could be done automatically.

Not yet found a plugin, filter, or other tool to do just fine, but I found some that may be the way to find the solution, they are in the branch:
https://github.com/carlosdelfino/micro-os-plus.github.io-source/tree/automatic-generate-toc.md

Also I realized that the original toc.md file is outdated.

[ilg-ul]

manually is a tiresome job

indeed. but fortunately this need not be done very often.

the original toc.md file is outdated.

then we'll update it. can you suggest the changes?

[carlosdelfino]

I make test with use of DocToc Node.js tool and get good results, a729148

but I need to adjust the file manually

Abou suggestions, the captions in toc do not match the subtitles in the original file. They are missing titles.

[carlosdelfino]

I will continue generating TOC.pt.md file as for translating the files when complete generate a final and consolidated file with all translations and using include_relative policy, thus including their respective toc.pt.md files generated by Node.js script doctoc ..

And finally generate one TOC.md file in English also using include_relative, what do you think?

please see the commit: 5ee37fe

[ilg-ul]

well, if you can automate the generation of the toc page with an external script, I have nothing agains, just that I would prefer the script to be added to the project, so I can run it too. if this is too complicated, I'll have to ask you to run the script from time to time for the English toc (and possibly for other languages, if needed).

as for include_relative, I did not understand where do you get the fragments to include. if you generate them with an external script, that wouldn't be a problem to concatenate the pieces and also generate the complete file.

[carlosdelfino]

It is not complicated, just laborious.

The script is easily added by running the command npm install -g doctoc once you have Node.js installed (I know are different tools each in a different language).

Then just enter the directory where the file that the TOC will be obtained, for example for basic-concepts.md I did as follows:

doctoc --github -s basic-concepts.pt.md> basic-concepts.toc.pt.md

I chose to separate each file with its own TOC, and use include_relative so that we can in the future to update the TOC without harming other files or have unpleasant surprises in concatenção process files.

Then this is the troublesome part, you need to edit the file and correct the references of anchors because they are created as locally on, and need to be absolute, but do not need to enter the site, just add the contents of the permalinkdo original file in markdown.

I think so is the best way for this automatic generation
A exemple result: https://github.com/carlosdelfino/micro-os-plus.github.io-source/blob/a72914859eaeb98dea13b7469a0db80432269584/pages/user-manual/basic-concepts.toc.pt.md

[ilg-ul]

just laborious

then it isn't very practical

my view on automating things is that if the user needs to do something more than starting a script, it is too complicated (for the user). and a sign of a poor design for the programmer.

on the other hand, the script can be as complex as needed.

examples of such "do it all in a single script" are the qemu/openocd build scripts; one script, in one run on my Mac, builds the macOS, Debian, and Windows install/setup packages, in 32/64-bits.

---

in our case, perhaps a better solution can be imagined.

as you might have noticed, I already have a Ruby plug-in in the project, that I use to generate the in-page TOC. what if we modify it to write the toc to a file, in the proper format, ready to be included it in the master TOC?

[carlosdelfino]

Only those who keep the site does need to run this script when have need to update the external TOC section. There will be no user need do it.That such a analyzing the hypothesis migrate the user manual for GitBook?We will have to worry only to the adopted layout, the process is very similar to the Jekyll and more appropriate to the content of the profile.

[ilg-ul]

There will be no user need do it

well, I am the user of my scripts, and perhaps I am even more lazy than regular users, don't I deserve an easy life? ;-)

migrate the user manual for GitBook?

this is one possible solution, but I'm not sure it is very practical.

the point is that currently I think that having the manual available on-line is still useful. if we want to use GitBook, probably we need to give up maintaining the current pages in Jekyll, otherwise we have to maintain two versions, which is not exactly nice.

if we could convert (with a script!) the current user manual to a GitBook repo, that would be a solution to have a PDF version of the manuals.

but for a true manual, we would also need to include the API reference pages, which are generated by Doxygen, and converting them (by another script) would be another challenge.

[carlosdelfino]

We can try to talk on Skype?
so I try to explain how it would use the Gitbook as transparent as possible, with clear visual exception to the layout level.

[carlosdelfino]

if I give more suggestions,

I would suggest you three types of written materials.

The site with news and calls for experiments, small articles proposing the use of OUs and could be written in various languages according to demand, generated by Jekyll.

The Handbook, which describe basic concepts, forms of use, instructions for troubleshooting. Exatamene what is within the pages / user-manual / using Gibook.

The API documentation, generated based on the comments in the source, using the Doxygem.

This trio is perfect for all work well, but lost by the lack of consolidation in the layout, which is not big problem

[ilg-ul]

... Skype?

yes, but this evening I'm not sure I can return to the computer in time.

Liviu

[ilg-ul]

three types of written materials

does this mean to move the user manual to GitBook and remove it from Jekyll? this would mean using GitBook online publishing feature, and also the PDF generating feature.

I only did some very simple tests with GitBook, and do not have much experience with it. do you have such a public manual available on GitBook?

I see two problems with this approach:

• betting on GitBook's future; once we make the manuals public there, people will make links to that urls, and we need that urls more or less permanently
• the formatting features, which might not be great; some time ago, when I evaluated the service, there were not many formatting features, and the PDF look was modest.

my medium term for the PDF manual was to do it right, on macOS, using Pages, and have a really professional look of the resulting PDF. well, actually a friend offered to handle the formatting, once the text is ready, and I accepted his offer.

on the other hand, all professional products manuals that I checked, include a nicely formatted reference manual, either at the end of the user manual, or as a separate manual. (µC/OS-III being my favourite, in a single PDF; other manuals I checked are TreadX, SMX, embOS).

so... although initially I was enthusiastic about GitBook, now I don't know if it is the solution that we need.

if you have better experience with GitBook, please provide some links to evaluate.

[carlosdelfino]

I writing this http://ilp.ed.carlosdelfino.eti.br and the source is https://github.com/carlosdelfino/introducao-linguagem-programacao

And with GitBook, you have a folder _book_ is the same with_siteon Jekyll, and you can make them same with you do with jekyll, crate to projects a ùser-manual with _book content and a user-manual-source with raw files.

[carlosdelfino]

This example: https://arobenko.gitbooks.io/comms-protocols-cpp/
And this: https://arobenko.gitbooks.io/bare_metal_cpp/
And here have many books: https://www.gitbook.com/explore

I think Gitbook is improve to multilingual and better layouts.

[carlosdelfino]

I've been thinking the same with GitBook keep the table of contents will be a challenge, and you need to develop a script for it, I will not commit myself to this activity now, though Node.js attracts me more than Ruby for such activity, and I see that enjoy the DocToc is the way to get the perfect script. It would be an excelent opportunity to dominate it, but my want to keep my focus on C / C ++ and the Cortex-M.

About multi language in gitbook follows some links:

GitbookIO/gitbook#34
https://www.gitbook.com/book/supersuraccoon/gitbook_multilanguage_template/details