Following up: The previous thread didn't develop further, so I am taking that as consensus. Summary: We liked Bernd's and Jerome's and Wolf's suggestions to put a "Documentation" subproject under the https://gitlab.com/FreeDOS shared project in the FreeDOS GitLab, so we can share working on documentation, in markdown, and work in the open. I can automate (weekly? daily?) a process to pull that to a new "docs.freedos.org" site and convert (pandoc?) from markdown to html, so it's easy to view. We can use a similar process to create viewable documentation to include in the FreeDOS distribution, so users have access to the documentation on a running system.
What do we need to do next to set up a "Documentation" subproject (shared subdirectory) at https://gitlab.com/FreeDOS where we can start working on documentation? From the previous conversation, using markdown seems like the best way to go. We'll want to set up subdirectories for 'guides' and 'about' and 'info' (and later, 'help') Also: A former tech writing student of mine recently asked about contributing to the FreeDOS documentation - very convenient timing! So if we can set up the GitLab subproject, we'll have another volunteer ready to help! On Sat, Jul 6, 2024 at 12:16 PM Jim Hall <jh...@freedos.org> wrote: > > 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
