Re: [oi-dev] I'd like to help out.
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 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 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
Re: [oi-dev] I'd like to help out.
I'll be glad to test on a current iPad Pro. 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. Reg On Tuesday, June 1, 2021, 11:45:13 AM CDT, benn 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 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 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
Re: [oi-dev] I'd like to help out.
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 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
Re: [oi-dev] I'd like to help out.
On Fri, 28 May 2021 10:30:14 -0700 Chris wrote: > The docs -- their various locations && inconsistencies, has been a > *huge* peav of mine. I'd *love* to attack that problem. The main problem I can see is there's documentation split across the Wiki and the Docs. Having two separate places for a small project like OI doesn't seem efficient. > I can easily script out /all/ the (HTML/CSS) tags from the > documents. Making them all plain text. There's no need to do that now. The Docs are mostly markdown already. Mkdocs only uses a extra few HTML tags for drawing certain icons and boxes. The problem was that sometimes HTML had been used instead of markdown (i.e. Bold instead of **Bold**) when the pages were written. I've now gone through the pages and corrected most instances of this (see below). A few pages, mostly those in docs/books, will need to be rewritten as they use lists inside a table which is not proper markdown and cannot be converted to PDF with Pandoc. Andreas has already merged my changes. These consist of a fix to replace HTML with markdown in various docs and a complete reworking of the PDF conversion script - it can now recognize mkdocs divs, draw boxes, images, creates tables of contents etc. For anyone who is interested, there's a PDF copy of the 'getting started' page of the Handbook here: (https://github.com/OpenIndiana/oi-docs/files/6566753/getting-started.pdf). I tried to send this email with the PDF as an attachment earlier, but it didn't seem to get through? -- Regards, James ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] I'd like to help out.
For the documentation, you can read the notes on how to submiy oi-docs pull requests. For example I submitted TeXLive docs : http://docs.openindiana.org/handbook/community/texlive/index.html This documents how to install TeXLive 2020 and it is also possibleto upgrade to TexLive 2021. The steps to submit such updates are at: http://docs.openindiana.org/contrib/content/ See "contacting the documentation team" and read everything on MDL http://docs.openindiana.org/contrib/markdown/ http://docs.openindiana.org/contrib/getting-started/ regards, David Stes - Op 28 mei 2021 om 13:01 schreef Tony Brian Albers t...@kb.dk: > Hi guys, > > I'd like to take a crack at updating the OI documentation. Who should I > talk to regarding priorites etc.? > > > Thanks, > > /tony > -- > Tony Albers - Systems Architect - IT Development Royal Danish Library, > Victor Albecks Vej 1, 8000 Aarhus C, Denmark > Tel: +45 2566 2383 - CVR/SE: 2898 8842 - EAN: 5798000792142 > ___ > oi-dev mailing list > oi-dev@openindiana.org > https://openindiana.org/mailman/listinfo/oi-dev ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] I'd like to help out.
On 2021-05-28 10:05, James Madgwick wrote: On Fri, 28 May 2021 08:27:11 -0400 Austin Kim 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? I'm not sure there's a need for a documentation list at the moment. 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. 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). 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). The docs -- their various locations && inconsistencies, has been a *huge* peav of mine. I'd *love* to attack that problem. To that end && as a response to this thread; If someone has an archive of all the docs. I can easily script out /all/ the (HTML/CSS) tags from the documents. Making them all plain text. Where they can then be easily loaded into any MARKDOWN savvy (on||off)line editor to introduce the desired markdown markup. I can process hundreds of (X)HTML/CSS documents in seconds. I just need physical access to them to do it.. Thanks. --Chris James ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev -- ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] I'd like to help out.
On Fri, 28 May 2021 08:27:11 -0400 Austin Kim 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? I'm not sure there's a need for a documentation list at the moment. 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. 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). 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). James ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] I'd like to help out.
I'd like to suggest the "Getting Started.." document referenced in the GUI installer opening screen, but MIA; though there is an online version that may be OK. I've only read it briefly for information. Not for editorial matters. Reliable installation by a new user is critical. Reg On Friday, May 28, 2021, 06:01:36 AM CDT, Tony Brian Albers wrote: Hi guys, I'd like to take a crack at updating the OI documentation. Who should I talk to regarding priorites etc.? Thanks, /tony -- Tony Albers - Systems Architect - IT Development Royal Danish Library, Victor Albecks Vej 1, 8000 Aarhus C, Denmark Tel: +45 2566 2383 - CVR/SE: 2898 8842 - EAN: 5798000792142 ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] I'd like to help out.
On May 28, 2021, at 7:01 AM, Tony Brian Albers wrote: > > Hi guys, > > I'd like to take a crack at updating the OI documentation. Who should I > talk to regarding priorites etc.? > > > Thanks, > > /tony > -- > Tony Albers - Systems Architect - IT Development Royal Danish Library, This reminds me; is there anyone who can review my documentation “patch” submission of https://openindiana.org/pipermail/oi-dev/2021-January/032410.html and, if approved, merge it into the WWW site (or offer feedback on why that submission was rejected so that I can improve it for resubmission to meet the documentation team’s quality standards)? (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? Austin “We are responsible for actions performed in response to circumstances for which we are not responsible.” —Allan Massie, _A Question of Loyalties_, 1989 ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
[oi-dev] I'd like to help out.
Hi guys, I'd like to take a crack at updating the OI documentation. Who should I talk to regarding priorites etc.? Thanks, /tony -- Tony Albers - Systems Architect - IT Development Royal Danish Library, Victor Albecks Vej 1, 8000 Aarhus C, Denmark Tel: +45 2566 2383 - CVR/SE: 2898 8842 - EAN: 5798000792142 ___ oi-dev mailing list oi-dev@openindiana.org https://openindiana.org/mailman/listinfo/oi-dev
