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 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 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? Of course, considerably more important than pdf, epub, ... is generating content. That is of the utmost importance---my opinion. 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 there's a need for a documentation list at the moment. Agreed, there is so much to do, just pick whatever you perceive as necessary and where you can best make a contribution and off you go. If someone requires documentation on a particular item, then a ticket ought to be created. > 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. > 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? > Having taken a closer look what is involved, I'm happy to do the work > I've suggested in the GitHub issue. Hopefully this will get the docs > into a bit of a better state, ready for new/improved/updated content to > be added. > > 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. > James > > _______________________________________________ > oi-dev mailing list > oi-dev@openindiana.org > https://openindiana.org/mailman/listinfo/oi-dev Cheers Benny _______________________________________________ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev