+debian-live@lists.debian.org On 04/04/2020 11:57, jnqnfe@gmail.com wrote: > Hi Roland, Hello Lyndon, Thank you for your efforts to make the live-manual better. I'm adding the mailing list to the list of recipients, because the work is done by the live team (of which I'm not a member, just a person with interest in the project) and the team can decide on the future direction of the project. > I believe you were the person who spoke of being in the middle of a big> update to live-manual? Well big... I am working (with the little time that I have) on updating the live-manual, primarily such that all references to Alioth get removed. While doing so, I got to know the live building process and updated parts of the manual that got out-of-date over time. > I was just curious about the scope of your work. > > Does your work involve at all: > a. any redesign of the style of the pages (CSS, HTML structure). No, I don't intend to influence the output. > b. any change to the markup language and respective "build" tool used > for "building" the documentation (generation of HTML pages and PDFs). No, the markup language SiSU is not a common markup language, but for me it suits its purpose. > ...or is it just limited to rewriting content only? So it is mainly rewriting content and ensuring that the translations will be minimally affected (which will be a larger MR). > I ask because I made a relatively small change the other day to the > coding style section (submitted an MR which is pending review); I assume you are referring to https://salsa.debian.org/live-team/live-manual/-/merge_requests/22 > I made > the effort to "build" locally, and I was not impressed with the markup > language and especially the build tools. I'm also not very impressed > with the style of the pages either. Your are mentioning personal preferences, let's discuss some requirements later. > The build tool SiSU was my biggest gripe. I was not impressed with the > hundreds of megabytes of dozens of packages required for sisu-complete > installation, that it seemed to be generating a postgresql database on > installation, that it pulls in ruby and such, and the manual having to > give advice on speeding up a supposedly very slow build process (I > followed the tips to limit the scope of building, which was reasonably > quick, I did not explore how slow the worst case supposedly is). As far as I can see, SiSU was a nice tool at the time the live-manual was started. It apparently didn't catch on, as nowadays there are hardly any reverse-(build)dependencies on SiSU. However, SiSU allows the author to focus on the content without being bothered by layout decisions and markup. For the translators, the translation framework is also present, using the well-known po files. I am using 'mk-build-deps' to track build dependencies of projects that I work on. I have plenty of GBs on my hard disk to pull in any package that might be required. When I am done, I can uninstall the dependency package and all extra packages will be uninstalled. So I don't need to care much how many packages I install for working on a specific Debian package. > Just at the minute I'm taking a brief pause in my other work to > consider the possibility of whether there is a better, more modern, > lightweight, etc tool that could replace use of SiSU. Something > markdown/commonmark based perhaps. Or maybe if we just used plain HTML > directly, with a conversion tool to produce PDFs (if we want to be able > to make them). > > I don't think we need care about the database backed "search" mechanism > SiSU provides. Back when Alioth was still running, the database backend functioned as a kind of search engine. > And I expect we don't need the same translation stuff we > use for code; translations can just be copies of the english files, > translated... I disagree here. Having a standard translation framework in place is important to me. For me, translated files should take over the structure and as much of the markup from the original file as possible, and preferably only replace the English content. > Anyway, I just wanted to know whether you were already working on > anything in this area or just rewriting the text. Also I was wondering > how near completion you might be, as I'd not want to start any effort > (if I was to do it myself) to convert to a different markup and such > until your substantial rewrite was available to do it on, otherwise it > would just create a lot of extra work for one of us to rework things on > top of the other's changes obviously. I would rather ask whether any of the team members would be willing to do a review if all files will be touched. My proposal: * First gather consensus from the team whether a change is needed * When so, decide on a solution that matches the requirements Let me try to summarise the current state: As-is state: * The documentation is written in SiSU * The output is available in PDF (A4 and letter, each both in portrait and landscape), HTML, epub, odf and plain text * Translations in all document formats are generated for 9 languages (ca, de, es, fr, it, ja, pl, pt_BR, ro) * Dead links can be found using linkchecker on the html output * sisu-complete pulls in many packages * The latest build from the git branch master is available on https://live-team.pages.debian.net/live-manual/ * live-manual is packaged in Debian as live-manual, live-manual-epub, live-manual-html, live-manual-odf and live-manual-pdf Positive notes: * Sisu is well-supported with syntax highlighting * Proof-reading the English text is done by 'make PROOF=1', which takes only about 8 seconds on my computer. Negative notes: * Sisu has a few reverse build dependencies * sisu-complete brings a large list of dependencies, but can be replaced by a smaller list Personally, I see no immediate need to have this large transition/rewrite right now. A task within the live team, that I see will be more pressing, will be the generation of the standard live images (about which I shortly wrote on 2020-03-21T17:27). Current Debian Stable images are built with live-wrapper, which uses vmdebootstrap under the hood. vmdebootstrap depends on Python 2, and will not be present in the next version of Debian. I am not aware of something that provides a 1-to-1 replacement that will work on Debian Testing (and therefore the next release of Debian). With kind regards, Roland Clobus
Attachment:
signature.asc
Description: OpenPGP digital signature