On Sat, Jul 6, 2024 at 5: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.
Well, it won't be under "FDOS" because that's not "The FreeDOS Project." FDOS is Jeremy's project, I think. (I don't think I knew Jeremy was using the FreeDOS fish on the "FDOS" GitHub - he probably should use something else or it will confuse people to think that's an official FreeDOS GitHub.) I like the idea of putting the docs under the FreeDOS GitLab group at <https://gitlab.com/FreeDOS>. That's where we host a live copy of the source code, so it makes sense to put the documentation there too. The process is the same to download a zip archive of everything in a repository/folder. For example, anyone can download the code to Choice with this: https://gitlab.com/FreeDOS/base/choice/-/archive/master/choice-master.zip ..so it's easy enough to automate grabbing a snapshot of the Markdown docs as a zip file (GitLab also supports tar.gz, tar.bz2, and tar). > 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. It's actually pretty easy to create a "documentation site" without using a static site generator like Hugo. Once you have the Markdown files, it's just a matter of putting everything into a place that a display system can find it. That's pretty easy for me to set up. > From the beginning, we should put an emphasis on also generating proper > (with a table of contents etc.) PDFs from the documentation. I think we can do that automatically using pandoc, which we'd need to do anyway to turn Markdown into HTML. > 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. > > ? We should think about how to generate some form of index for the > documentation. This would be especially important for the DOS viewers. +1 Yes to all of that! I think creating the "front page" index will probably take a little coding so it's automated, but not hard. Jim _______________________________________________ Freedos-devel mailing list Freedos-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/freedos-devel
