Hi, On Fri, Jul 5, 2024 at 8:07 PM Jim Hall via Freedos-devel < freedos-devel@lists.sourceforge.net> wrote:
> I really like your suggestion of using GitHub and Markdown to make it > easier to write the docs, share the docs, and include the docs in the > FreeDOS distribution! That's more extensible than my suggestion of > having an online web-only place to host 'how-to' guides. Let me add to > your idea with another idea: > > I like the way this is going, but thought I'd add to that with what I'm doing with DOG and the documentation. I use a static website generator, hugo, which basically adds styling to the markdown I write for the docs. The generator takes the markdown and applies a theme and spits out HTML. You can see the source for it here: https://gitlab.com/sirwolf77/dogweb For something bigger with multiple contributors you could set it up on a website to regularly do a git pull to pull fresh content to the site. Authors would only need to commit to the git repository and then the automation would pull it to the site. > What if we use plain GitHub and Markdown to collect FreeDOS > documentation. I have the 'freedosproject' username there > <https://github.com/freedosproject/> but mostly so no one else would > grab the username. I've been using it to share some of the demo > programs I've written for the YouTube channel. Let's say we create a > "docs" repository under that. > The benefit of using plain GitHub over e.g. hugo is that you don't need to host the site anywhere, GitHub (or GitLab) would do it for you :) > I said in my email that I think more people are looking for long-form > documentation (walkthroughs, tutorials, how-tos, etc) but that I also > wanted to have a place to store other long-form content that isn't > "how-to" content. But maybe we should find a way to keep some > "wiki-like" topics too. Let's say we created 3 subdirectories inside > this "docs" repository: > > 1. 'guides' for long-form content like how-tos, walkthroughs, and > tutorials ("How to install FreeDOS," "How to set up networking," "How > to get started on the command line," .. and other how-tos) > > 2. 'about' for other long-form content that is more like "what-is" > content, like a copy of the FreeDOS Spec, the 1994 announcement, the > original manifesto, .. things like that > > 3. 'info' for short-form information that's not a "help" page, > basically the kind of topics we would have had on the wiki. Like a > short page to say what "virtual machine "means, what "BIOS" is, things > like that. > > Then everyone could contribute to that GitHub project, writing content > in Markdown. I think we'd want to have a "style guide" so that we > format things the same, but that's easy to do. (Like use '#' heading1 > for the title, 1-2 short paragraphs as an intro, then '##" heading2 > and '###' heading3 for section and subsection headings, .. keep it > simple.) > Hugo (and I'm sure other static website generators do it too) has a page template for this. We could have a base template also checked in, allowing contributors to simply copy it for a quick start :) > Contributing to the documentation in this way would be the same > process as contributing to any other open source project hosted on > GitHub. I'd suggest using a Creative Commons Attribution ShareAlike > license. > One thing to keep in mind is that if we include code either from the projects or as part of an article, we should always clarify the licence of the source code in the article. > We could also add a rule (style guide: "How to write FreeDOS how-tos > in Markdown") that topics should only link to other topics in the same > area - so 'info' topics can link to other 'info' topics. That would > make it easy for authors to crosslink to [virtual machine](vm.md) for > more information about virtual machines from an 'info' topic about > "VirtualBox," or crosslink to [zip files](zip.md) from an 'info' topic > about FreeDOS package files. Then you end up with the same effect as a > wiki, but implemented through Markdown on GitHub. > > And if we ensure that files use 8.3 naming (vm.md instead of > virtualmachine.md) that would make it easy to roll this into a > "documentation" package to include in the FreeDOS distribution. As a > quick implementation: we could automate a process to download a zip > file of the "docs" repository from GitHub, use sed to change the > ".md)" to ".htm)" link extensions in the text, run pandoc to convert > every Markdown file to HTML, then zip it up again as a FreeDOS > package. > I like this idea! I might copy this for DOG :D It seems that by using pandoc filters <https://stackoverflow.com/questions/40993488/convert-markdown-links-to-html-with-pandoc> you can do it in one go. On FreeDOS, we might be able to use HTML Help to view these files. I > think it's a matter of pointing HTML Help to the right directory. > > > And if we decide later we should still have a docs.freedos.org website > to display the 'guides' content with nice "FreeDOS" branding, that's > equally easy to automate a process to refresh that website from the > "docs" GitHub repository. Keep maintaining them in GitHub, just make a > (monthly?) copy to our own website to display them there. > I suppose here is where a static website generator would come in handy :) I'd go for an hourly or a daily checkout to make contributions go live faster. > And if we do this for general documentation, we might consider moving > the FreeDOS Help <https://home.mnet-online.de/willybilly/fdhelp-dos/> > to be hosted in this GitHub project, so we can continue to manage it > there. But that's probably another discussion thread. > I like this idea! Based on the feedback I got for DOG, I think that the FreeDOS Help site should be made a lot more prominent! Having an online manual even if the help is available inside DOS would be very nice. Sometimes you want to have the manual next to you when writing e.g. batch files. On a side note I didn't realize how extensive the FreeDOS docs are I think I want to explore them more, maybe adopt it for DOG 🤔 --Wolf -- |\_ | .\---. / ,__/ / /Wolf <wolf+...@bergenheim.net>_ > > > _______________________________________________ > Freedos-devel mailing list > Freedos-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/freedos-devel >
_______________________________________________ Freedos-devel mailing list Freedos-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/freedos-devel
