Hi, > On Jul 6, 2024, at 6:12 AM, Bernd Böckmann via Freedos-devel > <freedos-devel@lists.sourceforge.net> wrote: > > Like Jerome I also would prefer to put the repository under the Gitlab > FreeDOS group[1] or alternatively under the fdos[2] group at Github. Gitlab > would be the more logical choice, I think. But Github would have the benefit > that there are still more people with an account for it.
There is a 4th option. Since it is all text, it could live over at the FreeDOS Translation Project (aka FD-NLS)[5] on Github. But, I think the Gitlab FreeDOS group[1] is a better place. Actually, I think it would be better for the work at FD-NLS and FDOS to be maintained in the GitLab group. In part to consolidate things, but mainly, I think the permissions system on Gitlab is more flexible and better suited for large projects whose contributors come and go. However, both FD-NLS and FDOS existed before the Gitlab FreeDOS group. It is asking a lot of any contributor to those projects to move to a new location. Maybe someday they could be brought under the same umbrella. But for now, it is easier to just keep them where they are. > > I like Wolfs idea of automatically generating a "documentation site" from the > Git repository. He mentioned hugo[3] as a static site generator. This seems > to be a good fit. mdbook[4] would be a more documentation focussed software, > but is not nearly as flexible as hugo. Another nice feature of both is their Gitlab and Github Pages[6][7]. Used in combination with YAML and the CI/CD of those platforms, it could automatically create a themed browsable website of the documentation. As an example, over at FD-NLS[5], I have a script (that I run locally) which compares basic kitten style NLS translation files and checks for things like missing keys. The output of that script is also pushed to the remote project on GitHub. When that report changes, the CI/CD will update the GitHub pages to display the “pretty” html version[8] of the report regarding translation status. > > From the beginning, we should put an emphasis on also generating proper (with > a table of contents etc.) PDFs from the documentation. > > Like already mentioned, having the documentation in markdown format would > give us the opportunity to automate many things, like building an offline > documentation from it. As Jim noted, we should establish some form of code > style considering the constrains given by the different output formats and > target system we would like to support. A few things / questions come into my > mind: > > - Restrict to UTF-8 encoding to make conversion to different DOS codepages > for translated documentation straightforward > > - Verbatim text like code snippets should be restricted to 78 characters a > line, so that it fits without a line break on a DOS screen, or alternatively > create a viewer for it that supports horizontal scrolling on the verbatim > text while reflowing the "ordinary" text paragraphs. > > ? Technically, while I doubt anyone is using it at all, there is a 40 column > text mode. While probably not worth dealing with this it would not be a bad > thing to design everything that this could be supported at some time. > > ? Maybe using things like tables should be considered a "do not", because it > is questionable if these look good on a 80 (or even 40) column display when > converted to a different format for offline viewing under DOS. It could be > made to work if the tables get converted to verbatim text blocks and the > horizontal scrolling thing gets implemented in a DOS viewer. I think all the constraints could be enforced at commit/merge. A while back AndyStamp provided some “workflows” to the FD-NLS project that did some of what you suggest. Things like verifying the UTF-8 and codepage conversion files. Something similar could be done on either Git. > > ? We should think about how to generate some form of index for the > documentation. This would be especially important for the DOS viewers. > > > [1] https://gitlab.com/FreeDOS > [2] https://github.com/FDOS > [3] https://gohugo.io/ > [4] https://github.com/rust-lang/mdBook > > Greetings, Bernd > [5] https://github.com/shidel/fd-nls <https://github.com/shidel/fd-nls> [6] https://docs.gitlab.com/ee/user/project/pages/ <https://docs.gitlab.com/ee/user/project/pages/> [7] https://pages.github.com <https://pages.github.com/> [8] https://shidel.github.io/fd-nls/report.html <https://shidel.github.io/fd-nls/report.html> :-) Jerome
_______________________________________________ Freedos-devel mailing list Freedos-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/freedos-devel
