<div>                I'll be glad to test on a current iPad Pro.<br><br>I am accumulating all my electronics and computer documentation on one..  Finally, a solution to the great wall of manuals.  I bought it to hold music, but have yet to scan that.  The stuff I've loaded didn't need to be scanned.<br><br>Reg<br>            </div>            <div class="yahoo_quoted" style="margin:10px 0px 0px 0.8ex;border-left:1px solid #ccc;padding-left:1ex;">                        <div style="font-family:'Helvetica Neue', Helvetica, Arial, sans-serif;font-size:13px;color:#26282a;">                                <div>                    On Tuesday, June 1, 2021, 11:45:13 AM CDT, benn <benny.lyons@gmx.net> wrote:                </div>                <div><br></div>                <div><br></div>                <div><div dir="ltr">Hi,<br clear="none">The makepdf.sh sin was committed by me. As I don't particularly like reading<br clear="none">html, I used to convert the markup to pdf and epub, and I used a script to <br clear="none">do that. I only ever tested the epub on my own tablet. (Anyone else try the<br clear="none">epub?)<br clear="none">Someone on the OI ML saw a generated pdf of some of the OI docs (if I recall<br clear="none">correctly) and asked how? so makepdf.sh came into being. It was  originally<br clear="none">in Python, but we still had problems with the Python version, so I wrote it<br clear="none">in Bash.<br clear="none"><br clear="none">It is a quick hack. The results (the pdf quality) are awful in my opinion, <br clear="none">but maybe it can rescued, I'm not sure.<br clear="none"><br clear="none">It was conceived to be a prototype to develop something better after <br clear="none">getting feedback (alas none hitherto)?<br clear="none">It should be ported to Python which is easy to do, now that we have a nice<br clear="none">stable Python version on OI (3.x).  I'm not sure whether pandoc was the best <br clear="none">way either, maybe there is a better way, I wasn't sure at the time. We didn't <br clear="none">have a texlive package at that time either on OI, (great that we now have one<br clear="none">on OI really, really happy about that), so I used Linux.<br clear="none"><br clear="none">I'd be happy to add improvements, and will have a look at issue 181 (thanks!)<br clear="none">If you have any specific improvement requests, better add an issue _for<br clear="none">each request_. Proposals on _how_ to go about implementing these improvements<br clear="none">would also be greatly appreciated (add to the ticket), or simply use the <br clear="none">oi-docs ML.<br clear="none"><br clear="none">Someone mentioned lack of documentation for the script. Well, it is all there <br clear="none">in the script, try:<br clear="none">    makepdf.sh -h<br clear="none"><br clear="none">I could easily add a manpage? But the script currently does so little I wonder<br clear="none">if this is necessary. Maybe in the future.  Anyway, do we want to keep makepdf.sh?<br clear="none">and the options are terrible (-f for 'input', -t for output format? I must have<br clear="none">been suffering from something at the time). These must change.  Moreover, the <br clear="none">title, makepdf.sh, is severely misguided as it does epub and other formats. <br clear="none">(Please, lets not start a discussion on new titles or names: better save your<br clear="none">time to write documentation!)<br clear="none"><br clear="none">I think the foremost necessity is to obtain good quality for the pdf (and then <br clear="none">the epub and mobi formats should be easy); but is this really possible?  This<br clear="none">is easily achieved using LaTeX directly; but via markup?<br clear="none"><br clear="none">Of course, considerably more important than pdf, epub, ... is generating <br clear="none">content. That is of the utmost importance---my opinion.<br clear="none"><br clear="none"><br clear="none"><br clear="none">On Fri, 2021-05-28 at 18:05 +0100, James Madgwick wrote:<br clear="none">> On Fri, 28 May 2021 08:27:11 -0400<br clear="none">> Austin Kim <<a shape="rect" ymailto="mailto:freennix@gmail.com" href="mailto:freennix@gmail.com">freennix@gmail.com</a>> wrote:<br clear="none">> > (Any doc contributions I could make will be few and far between due<br clear="none">> > to time, but, maybe something > nothing?)<br clear="none">> ><br clear="none">> > Also, y’all’s thoughts about possibly setting up an “oi-doc” mailing<br clear="none">> > list in the future for the OI documentation project?<br clear="none">We have a ML specifically for OI docs: <a shape="rect" ymailto="mailto:docs@openindiana.org." href="mailto:docs@openindiana.org.">docs@openindiana.org.</a><br clear="none"><br clear="none"><br clear="none">> I'm not sure there's a need for a documentation list at the moment.<br clear="none">Agreed, there is so much to do, just pick whatever you perceive as necessary<br clear="none">and where you can best make a contribution and off you go. If someone requires<br clear="none">documentation on a particular item, then a ticket ought to be created.<br clear="none">> I have suggested some meta improvements to the existing docs - fixing<br clear="none">> PDF generation (<a shape="rect" href="https://github.com/OpenIndiana/oi-docs/issues/181" target="_blank">https://github.com/OpenIndiana/oi-docs/issues/181</a>).<br clear="none">> Andreas said I should post on here so the community can have full sight<br clear="none">> of this proposal.<br clear="none">I'll have a look at this and get back.<br clear="none">> So far I've had a look at how the documentation can be cleaned up to<br clear="none">> allow a useful conversion to PDF. This will require lots of small edits<br clear="none">> to replace any existing HTML markup with markdown (where this is<br clear="none">> possible). At the moment there's a few places where HTML has been used<br clear="none">> instead of markdown and this doesn't work with Pandoc (the program used<br clear="none">> to create PDF from markdown).<br clear="none">Maybe these edits can be performed in makepdf.sh? or whatever.py?<br clear="none"><br clear="none">> Having taken a closer look what is involved, I'm happy to do the work<br clear="none">> I've suggested in the GitHub issue. Hopefully this will get the docs<br clear="none">> into a bit of a better state, ready for new/improved/updated content to<br clear="none">> be added.<br clear="none">><br clear="none">> Any thought's about the PDF docs themselves? I know BSDs have a single<br clear="none">> PDF manual, which is one file, as well as an HTML website. Currently OI<br clear="none">> has only a website (plus - if the work I suggest is done - PDFs for each<br clear="none">> page of the website).<br clear="none">It is a simple matter in the script, to add an option to merge various pdfs<br clear="none">into a single pdf; but that is something for when we actually have enough<br clear="none">material, i.e., content. Anyway, I personally don't want developer stuff <br clear="none">mixed with admin and user stuff in the same document. It might be useful <br clear="none">to generate a single admin, developer, i.e. a single pdf for each directory.<br clear="none"><br clear="none"><br clear="none">> James<br clear="none">><br clear="none">> _______________________________________________<br clear="none">> oi-dev mailing list<br clear="none">> <a shape="rect" ymailto="mailto:oi-dev@openindiana.org" href="mailto:oi-dev@openindiana.org">oi-dev@openindiana.org</a><br clear="none">> <a shape="rect" href="https://openindiana.org/mailman/listinfo/oi-dev" target="_blank">https://openindiana.org/mailman/listinfo/oi-dev</a><br clear="none"><br clear="none">Cheers<br clear="none">Benny<div class="yqt9860101683" id="yqtfd64483"><br clear="none"><br clear="none"><br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">oi-dev mailing list<br clear="none"><a shape="rect" ymailto="mailto:oi-dev@openindiana.org" href="mailto:oi-dev@openindiana.org">oi-dev@openindiana.org</a><br clear="none"><a shape="rect" href="https://openindiana.org/mailman/listinfo/oi-dev" target="_blank">https://openindiana.org/mailman/listinfo/oi-dev</a><br clear="none"></div></div></div>            </div>                </div>