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

[benn]

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 <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 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 at openindiana.org
> https://openindiana.org/mailman/listinfo/oi-dev

Cheers
Benny