[oi-dev] I'd like to help out.

[James Madgwick]

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.lyons at 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 <freennix at 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: docs at 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