Hi Benny, First of all, apologies for picking up this work already and making changes. I've closed the PR and issue but do please reopen/add comments as necessary. I'm new here and getting the hang of how the community does things, I should have waited a little longer.
On Tue, 01 Jun 2021 18:44:11 +0200 benn <benny.ly...@gmx.net> wrote: > Hi, > The makepdf.sh sin was committed by me. As I don't particularly like > reading html, I used to convert the markup to pdf and epub, and I > used a script to do that. I only ever tested the epub on my own > tablet. (Anyone else try the epub?) > Someone on the OI ML saw a generated pdf of some of the OI docs (if I > recall correctly) and asked how? so makepdf.sh came into being. It > was originally in Python, but we still had problems with the Python > version, so I wrote it in Bash. > > It is a quick hack. The results (the pdf quality) are awful in my > opinion, but maybe it can rescued, I'm not sure. > > It was conceived to be a prototype to develop something better after > getting feedback (alas none hitherto)? > It should be ported to Python which is easy to do, now that we have a > nice stable Python version on OI (3.x). I'm not sure whether pandoc > was the best way either, maybe there is a better way, I wasn't sure > at the time. We didn't have a texlive package at that time either on > OI, (great that we now have one on OI really, really happy about > that), so I used Linux. > > I'd be happy to add improvements, and will have a look at issue 181 > (thanks!) If you have any specific improvement requests, better add > an issue _for each request_. Proposals on _how_ to go about > implementing these improvements would also be greatly appreciated > (add to the ticket), or simply use the oi-docs ML. > > Someone mentioned lack of documentation for the script. Well, it is > all there in the script, try: > makepdf.sh -h Yes that documentation is quite sufficient. I was thinking about documenting the purpose of the script in the handbook itself. As I've recently made changes I'll complete that. > I could easily add a manpage? But the script currently does so little > I wonder if this is necessary. Maybe in the future. Anyway, do we > want to keep makepdf.sh? and the options are terrible (-f for > 'input', -t for output format? I must have been suffering from > something at the time). These must change. Moreover, the title, > makepdf.sh, is severely misguided as it does epub and other formats. > (Please, lets not start a discussion on new titles or names: better > save your time to write documentation!) I didn't notice an option for epub, that's certainly something that could be added quite easily. Potentially with a trivial change - if Pandoc generates them using LaTex. > I think the foremost necessity is to obtain good quality for the pdf > (and then the epub and mobi formats should be easy); but is this > really possible? This is easily achieved using LaTeX directly; but > via markup? I got around this by converting some of the HTML markup into LaTex with a Pandoc filter and inserting Latex headers. This is the current result: https://github.com/OpenIndiana/oi-docs/files/6566753/getting-started.pdf > Of course, considerably more important than pdf, epub, ... is > generating content. That is of the utmost importance---my opinion. I agree, I'm hoping to contribute some further improvements to the content itself in the coming weeks/months. > On Fri, 2021-05-28 at 18:05 +0100, James Madgwick wrote: > > On Fri, 28 May 2021 08:27:11 -0400 > > Austin Kim <freen...@gmail.com> wrote: > > > (Any doc contributions I could make will be few and far between > > > due to time, but, maybe something > nothing?) > > > > > > Also, y’all’s thoughts about possibly setting up an “oi-doc” > > > mailing list in the future for the OI documentation project? > We have a ML specifically for OI docs: d...@openindiana.org. I'm not sure if that address is active. I don't see it listed here: https://openindiana.org/mailman/listinfo > > I have suggested some meta improvements to the existing docs - > > fixing PDF generation > > (https://github.com/OpenIndiana/oi-docs/issues/181). Andreas said I > > should post on here so the community can have full sight of this > > proposal. > I'll have a look at this and get back. Again, apologies for closing this so rapidly. > > So far I've had a look at how the documentation can be cleaned up to > > allow a useful conversion to PDF. This will require lots of small > > edits to replace any existing HTML markup with markdown (where this > > is possible). At the moment there's a few places where HTML has > > been used instead of markdown and this doesn't work with Pandoc > > (the program used to create PDF from markdown). > Maybe these edits can be performed in makepdf.sh? or whatever.py? I took the more time intensive option to clean up the HTML manually and replace it with markdown. Most pages had only a few snippets. The rest of the conversion occurs through the Pandooc Lua filter (pandoc-filter.lua). > > Any thought's about the PDF docs themselves? I know BSDs have a > > single PDF manual, which is one file, as well as an HTML website. > > Currently OI has only a website (plus - if the work I suggest is > > done - PDFs for each page of the website). > It is a simple matter in the script, to add an option to merge > various pdfs into a single pdf; but that is something for when we > actually have enough material, i.e., content. Anyway, I personally > don't want developer stuff mixed with admin and user stuff in the > same document. It might be useful to generate a single admin, > developer, i.e. a single pdf for each directory. That sounds like a good approach. At the moment, as you say, it's not too important I don't think as most of pages are quite lacking in content. -- Regards, James _______________________________________________ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev