Re: User Docs for DebianEdu
On Fri, May 12, 2023 at 12:56 PM Dashamir Hoxha wrote: > Hi, > > On Fri, Mar 31, 2023 at 11:09 PM Dashamir Hoxha > wrote: > > I'd like to inform you that recently we (me, Mike and Holger) submitted > a project proposal to Google Season of Docs: > > > https://salsa.debian.org/debian-edu/funding/gsod/-/blob/main/2023/project-proposal.md > > As a follow up, although this project was not sponsored by GSoD, I may > still find some time to work on it during the summer. > > To get started, we should create these two repos on > https://salsa.debian.org/debian-edu and give me full access on them: > - docs > - debian-edu.pages.debian.net (yes, it should be named like this) > > According to the salsa docs ( > https://wiki.debian.org/Salsa/Doc#Web_page_hosting), the content of the > first repo will be available on this url: > https://debian-edu.pages.debian.net/docs/ , and the content of the second > repo (which will be used for the new homepage) will be available on the > url: https://debian-edu.pages.debian.net/ (as soon as I push some content > to them). > Sorry, I have been busy with other things and couldn't find time for it. I just started this repo: https://salsa.debian.org/debian-edu/docs (better late than never). According to the salsa docs, the auto-generated doc pages should be available at this url: - https://debian-edu.pages.debian.net/docs/ However, what actually happens is that this url is forwarded to a random url. I don't know why, maybe the salsa maintainers should be asked about this. I am aware (from past discussions) that not everybody is happy with this documentation approach/toolchain. I just created this small repo as a seed. If people like it, it will grow over time. Otherwise it will be forgotten and will die. Or it can be removed immediately; I just spent a couple of days with it, not a big deal. Kind regards, Dashamir
Re: User Docs for DebianEdu
On Fri, May 12, 2023 at 1:11 PM Petter Reinholdtsen wrote: > > While it is unclear to me if it is a good idea to leave the Debian wiki > when writing documentation, I leave that to others to figure out. > I leave that to others too. I just wanted to point out that when selecting source format for the > documentation, I strongly recommend using a format that can be converted > to docobok using pandoc, to be able to create good looking documentation > in both HTML, PDF and ePub format. > > It is also a very good idea to ensure the format selected is well > handled by po4a to allow the documents to be translated into non-English > > Personally I would recommend Restructured text (rst) over markdown, as > it has a richer vocabulary than markdown. I recommend Restructured text > over Asciidoc as the latter is less well supported by po4a. > My first choice would be AsciiDoc+Antora because I have some experience with them. I think that the AsciiDoc syntax provides the best mapping to the DocBook features. Pandoc cannot handle it well precisely because its structure is richer than what pandoc can support. But we can use Asciidoctor instead to generate DocBook from AsciiDoc: https://docs.asciidoctor.org/asciidoctor/latest/docbook-backend/ I have not really explored po4a (and if you ask me it is a bad approach to translation), but it seems like it is supported: https://gitlab.com/antora-ui-custom/antora-i18n#user-content-po4a Cannot say whether this support is better or worse compared to Restructured text. Kind regards, Dashamir
RE: User Docs for DebianEdu
Date: Fri, 12 May 2023 11:35:01 + From: Holger Levsen To: debian-edu@lists.debian.org > It's not the lockdown which is unbearable, but the virus. Whilst it is off-topic, I think that statement, from Holger's signature, is very well put. .. Bret Busby Armadale West Australia (UTC+0800) ..
Re: User Docs for DebianEdu
On Fri, May 12, 2023 at 01:11:07PM +0200, Petter Reinholdtsen wrote: > While it is unclear to me if it is a good idea to leave the Debian wiki > when writing documentation, I leave that to others to figure out. I also very much doubt this... > I just wanted to point out that when selecting source format for the > documentation, I strongly recommend using a format that can be converted > to docobok using pandoc, to be able to create good looking documentation > in both HTML, PDF and ePub format. > > It is also a very good idea to ensure the format selected is well > handled by po4a to allow the documents to be translated into non-English > languages using the tools currently used by translators YES -- cheers, Holger ⢀⣴⠾⠻⢶⣦⠀ ⣾⠁⢠⠒⠀⣿⡁ holger@(debian|reproducible-builds|layer-acht).org ⢿⡄⠘⠷⠚⠋⠀ OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C ⠈⠳⣄ It's not the lockdown which is unbearable, but the virus. signature.asc Description: PGP signature
Re: User Docs for DebianEdu
While it is unclear to me if it is a good idea to leave the Debian wiki when writing documentation, I leave that to others to figure out. I just wanted to point out that when selecting source format for the documentation, I strongly recommend using a format that can be converted to docobok using pandoc, to be able to create good looking documentation in both HTML, PDF and ePub format. It is also a very good idea to ensure the format selected is well handled by po4a to allow the documents to be translated into non-English languages using the tools currently used by translators of both the Debian Edu documentation and free software, ref https://people.skolelinux.org/pere/blog/From_English_wiki_to_translated_PDF_and_epub_via_Docbook.html >. Note, since the blog post was written, we started using Hosted Weblate to handle most translations, see https://hosted.weblate.org/projects/debian-edu-documentation/ > for the current status. Personally I would recommend Restructured text (rst) over markdown, as it has a richer vocabulary than markdown. I recommend Restructured text over Asciidoc as the latter is less well supported by po4a. -- Happy hacking Petter Reinholdtsen
User Docs for DebianEdu
Hi, On Fri, Mar 31, 2023 at 11:09 PM Dashamir Hoxha wrote: > I'd like to inform you that recently we (me, Mike and Holger) submitted a project proposal to Google Season of Docs: > https://salsa.debian.org/debian-edu/funding/gsod/-/blob/main/2023/project-proposal.md As a follow up, although this project was not sponsored by GSoD, I may still find some time to work on it during the summer. To get started, we should create these two repos on https://salsa.debian.org/debian-edu and give me full access on them: - docs - debian-edu.pages.debian.net (yes, it should be named like this) According to the salsa docs ( https://wiki.debian.org/Salsa/Doc#Web_page_hosting), the content of the first repo will be available on this url: https://debian-edu.pages.debian.net/docs/ , and the content of the second repo (which will be used for the new homepage) will be available on the url: https://debian-edu.pages.debian.net/ (as soon as I push some content to them). I do have some experience with static websites that are published on gitlab.com, and I believe that it should be almost the same on salsa. Kind regards, Dashamir
