Puppy Linux Discussion Forum Forum Index Puppy Linux Discussion Forum
Puppy HOME page : puppylinux.com
"THE" alternative forum : puppylinux.info
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

The time now is Fri 13 Dec 2019, 18:26
All times are UTC - 4
 Forum index » Taking the Puppy out for a walk » Suggestions
Better Documentation
Moderators: Flash, Ian, JohnMurga
Post new topic   Reply to topic View previous topic :: View next topic
Page 1 of 2 [20 Posts]   Goto page: 1, 2 Next
Author Message
sc0ttman


Joined: 16 Sep 2009
Posts: 2772
Location: UK

PostPosted: Tue 12 Sep 2017, 13:02    Post subject:  Better Documentation
Subject description: We can auto-generate the online documentation
 

Suggestion: Generating standardised docs by script for each [official or major] release.

In short:
- ensure every woof build can generate its own docs
- give each official release its own documentation space online
- use PmWiki (or OddMuse, similar) for main site AND for the Wiki
- standardised wiki and doc pages for each release, nicely organised online
- only ONE location for main site, releases notes, handbook, wiki, bug tracking, forum (iframe this one in)
- create shell scripts to run after a good Woof build:
--- auto generate PMWiki pages (grab templates, replace vars, done)
--- build whole docs package for that release (create the file structure we need online)
--- install the pages online to puppylinux.org (ftp them onine)
--- build a PET so people can have the Wiki locally to work on (etc)
- a github repo for the generated docs .. a branch for each release/puplet, main branch containing the templates from which the real docs are generated

We can achieve the above (fairly) easily, by learning (even borrowing/forking) from
work from others...

More Info:

CRUX Linux (and Arch Linux) produce better docs, and theirs are easier to maintain:

- their docs are auto-generarated for each build/release
- standardised docs and release notes for each official release
- central Wiki, one place with all major information
- good, long pages with lots of reproducible code examples

Puppys docs are hard to maintain:

- docs manually created for each release, no specific format or location
- sporadic, terse (even cryptic), sparse, scattered around many sites
- the wiki is outdated, MANY broken links, no structure at all
- wiki not organised by release .. pet are listed all over the place only little notes as to which Pup they might be for
- no standardised formats for any releases at all
- etc

The poor guys who run around trying to keep our Wikis and docs (at various random
places) up to date are legends in my book.. A totally painful, and probably thankless task..

We need to make life easier for them, reduce their workload and STANDARDISE our
docs with each official release...Even for each Puplet release, bugfix release, RC
(release candidate) and so on ...


How to do it better:

If the scripts to build the documentation are included in Woof, then we can auto-build
ever improving docs, specific to the Puppy built, with standardised pages, layouts, etc.


Each time a Puppy is woof-built, its (standardised) docs should be generated, ready to
drop into the right location on puppylinux.org...

The home page, Wiki (and any other pages that need to be updated to include info about
the latest release) could be auto-generated too .. They would simply replace the old ones..

CRUX Linux 3.3 has an excellent Handbook.

But in fact, it is *mostly* the same as the CRUX Linux 3.2 Handbook.
.. and the CRUX Linux 2.7 Handbook

Their Wiki get updated as they update to a new release, they dont keep separate Wikis
for each release.

(We manually update docs and stuff ad-hoc all the time at many different locations..)

The CRUX devs simply auto-generate PmWiki pages for their main site, for their Handbooks,
Release Notes, and most other docs, whenever they do a new release.


Less work, less repetition, better docs 'coverage', nicer docs, one central location, using
only PmWiki (which is a flat file, lightweight, PHP based Wiki, with Markdown support!)

Adding the markdown plugin to PmWiki means our docs could be generated for PmWiki,
and for GitHub at the same time!

The CRUX website is nearly all one script (PmWiki), and organised like so:

https://crux.nu/Main/ <-- their main site (a PmWiki site, red theme)
https://crux.nu/Wiki/ <-- their Wiki (the same PmWiki site, but with a blue theme)


https://crux.nu/Wiki/HomePage <-- small but effective .. covers basics of most common user tasks.. not much version specific info in there..

https://crux.nu/Main/Development <-- just a page of the main (red) site

https://crux.nu/portdb/ <-- just a page with a table, on the main (red) site

https://crux.nu/bugs/ <-- not a PmWiki page, powered by http://www.flyspray.org/

That is their only site... all on one domain .. Main site, wiki, portdb (users repo list) all in one script.. Then flyspray for bugtracking..
Simpler than ours, better than ours..

And now their Documentation:

Release Notes:

https://crux.nu/Main/ReleaseNotes3-3
https://crux.nu/Main/ReleaseNotes3-2
...
https://crux.nu/Main/ReleaseNotes2-6

Their handbooks:

https://crux.nu/Main/Handbook3-3
https://crux.nu/Main/Handbook3-2
https://crux.nu/Main/Handbook3-1
...
https://crux.nu/Main/Handbook2-6


If each official Puppy release had its own, specific Wiki and Manual pages, links to them could be auto-generated too.

http://wiki.puppylinux.org/Releases/$DISTRO_VERSION/Homepage
http://wiki.puppylinux.org/Releases/$DISTRO_VERSION/Manual

...etc



Conclusion:

We need one central site, with release notes and handbooks that are standardised, versioned and automatically
generated with each release.

We could power our main site, Wiki and contrib-repo database all on the same site, quite easy to auto-update
as new releases come out.

We could have a bug tracker (flyspray does look nice! .. and Fossil) at the same place as our main site and Wiki..
Puppy could simply have a Bugs info page, with links to GitHub Issues,
and some more to GitHub Project, Roadmap page, Forum, etc.

We should copy the excellent file structure of CRUX to ensure every release gets it own documentation space,
with info specific that that puppy (repo names, pkg names, version numbers, etc)...

_________________
Pkg, mdsh, Woofy, Akita, VLC-GTK, Search
Back to top
View user's profile Send private message 
sc0ttman


Joined: 16 Sep 2009
Posts: 2772
Location: UK

PostPosted: Wed 09 Oct 2019, 14:47    Post subject:  

Well, as no one else picked this up .. I did ..

I made a thing that can do the above - generate documentation for a Puppy release in an automated way.

The thing is called `mdsh` (Markdown + Shell) ...

It's here: https://github.com/sc0ttj/mdsh/

By default it produces blogs... but it can produce any kind of website...

An example blog is here: https://sc0ttj.github.io/mdsh/

You can put shell code in your Markdown files, and by changing some vars and rebuilding your page, you can generate lots of different HTML files from a single Markdown file.

For example, in a Markdown file called "foo.mdsh":

Code:

# Some header

## Puppy version <?bash echo $DISTRO_NAME ;?>


Then just run:

Code:
source /etc/DISTRO_SPECS
rebuild foo.mdsh > ${DISTRO_NAME}.html


Obviously, you can grab info for different puppies or run the rebuild command on different Puppies, to produce different HTML pages for each Puppy version - all based on the same templates, but with version specific stuff in there too!

Smile

I'll be finishing up some stuff in `mdsh` soon and will create a simple Puppy handbook, and generate a handbook for a couple of different Puppies as a demo ...

Then, hopefully, mdsh will be adopted into Woof-CE, and at the end of a successful build, the user can be asked to generate various web pages/sites:

- Release notes
- Handbook
- Packages site (like https://packages.debian.org/stable/ etc)

These could be uploaded to PuppyLinux.com/${DISTRO_NAME}/${DISTRO_VERSION}/<some-dir>/<some file>.html

And quite frankly, instead of FTPing files to paid servers like it's the 90s, if we pulled our fingers out and hosted the main Puppy site as a static site on GitHub Pages, Netlify, Gitlab Pages (or similar) then hosting would be 100% free...

....AND we'd be able to auto generate AND publish the new webpages as a "Pull Request" - so it can be reviewed before being accepted and published proper (with just a few clicks)..

For the more advanced peeps out there, we could even use GitHub Actions (or GitLab Runners) to do server-side stuff for free, triggered each time an update is pushed (uploaded) to the sites repo...

This would include stuff like

- automatically compress CSS, images, JSON, etc
- checking uploaded HTML, JS, CSS etc for syntax errors, etc
- auto fix CSS errors, add better browser compatibility
- etc, etc

or more advance stuff (for another day):

- auto generate google AMP pages
- automatically posting to social media when a new release is out

Let's do it people! ...

Who is the maintainer of PuppyLinux.com?

_________________
Pkg, mdsh, Woofy, Akita, VLC-GTK, Search
Back to top
View user's profile Send private message 
musher0

Joined: 04 Jan 2009
Posts: 14544
Location: Gatineau (Qc), Canada

PostPosted: Wed 09 Oct 2019, 15:21    Post subject:  

It would be nice if it included the docs for the utilities included in the Pup, e.g. man pages,
docs for Abiword, Geany, MTPaint, etc.

_________________
musher0
~~~~~~~~~~
Je suis né pour aimer et non pas pour haïr. (Sophocle) /
I was born to love and not to hate. (Sophocles)
Back to top
View user's profile Send private message 
Flash
Official Dog Handler


Joined: 04 May 2005
Posts: 13394
Location: Arizona USA

PostPosted: Wed 09 Oct 2019, 20:18    Post subject:  

It seems to me that what's needed is a checklist that needs to be filled out. Something in a wiki, so anyone could add items to the checklist.
Back to top
View user's profile Send private message 
rockedge


Joined: 11 Apr 2012
Posts: 1357
Location: Connecticut, United States

PostPosted: Wed 09 Oct 2019, 20:36    Post subject:  

totally agree the documents need some standard, a check list would be a start. The shear size of all the Puppy Linux information out there is staggering. To find those solutions for many things and create a set of documents would be a formidable job it seems
Back to top
View user's profile Send private message Visit poster's website 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15556
Location: Paradox Realm

PostPosted: Wed 09 Oct 2019, 22:07    Post subject:  

Quote:
Who is the maintainer of PuppyLinux.com?


It might be Mick Armadio ... ? Used to be raffy?

This page is a little out of date Embarassed
http://wikka.puppylinux.com/PuppyOrganization

Well done on the documenting initiative Cool

Puppy doacracy
What you do, gets done

_________________
Puppy on Raspberry Pi Release Candidate Cool
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html Very Happy
Back to top
View user's profile Send private message Visit poster's website 
01micko


Joined: 11 Oct 2008
Posts: 8739
Location: qld

PostPosted: Thu 10 Oct 2019, 02:46    Post subject:  

If you want to change http://puppylinux.com issue a pull request at https://github.com/puppylinux-woof-CE/puppylinux-woof-CE.github.io

We are all the maintainers.

_________________
Puppy Linux Blog - contact me for access
Back to top
View user's profile Send private message Visit poster's website 
Mike Walsh


Joined: 28 Jun 2014
Posts: 5661
Location: King's Lynn, UK.

PostPosted: Thu 10 Oct 2019, 14:44    Post subject:  

Don't take this the wrong way, kiddiwinks, but it's starting to sound as though Pup's gonna end up as a 'clone' of every other Linux distro out there....only more so.

I thought we as a community were proud of our individuality? Seems to be heading down the khazi at a fast clip..... Rolling Eyes

(*shrug*)


Mike. Wink

_________________
MY 'PUPPY' PACKAGES

Back to top
View user's profile Send private message 
sc0ttman


Joined: 16 Sep 2009
Posts: 2772
Location: UK

PostPosted: Thu 10 Oct 2019, 17:17    Post subject:  

Mike Walsh wrote:
Don't take this the wrong way, kiddiwinks, but it's starting to sound as though Pup's gonna end up as a 'clone' of every other Linux distro out there....only more so.

I thought we as a community were proud of our individuality? Seems to be heading down the khazi at a fast clip..... Rolling Eyes

(*shrug*)


Mike. Wink

I don't see what the objection is here...

Puppy would still have its own build tool, custom website etc, etc, just an additional, puppy-only tool for easier generating of the standard docs that *should* be released with each official or major release..

The handbook I make (i'm not gonna rush, work is hectic), will be dead simple, easy to add to, and cover the basics - installation, setup, downloading packages, using the main system tools, etc ..

Others will be able to add to it very easily..

_________________
Pkg, mdsh, Woofy, Akita, VLC-GTK, Search
Back to top
View user's profile Send private message 
Mike Walsh


Joined: 28 Jun 2014
Posts: 5661
Location: King's Lynn, UK.

PostPosted: Thu 10 Oct 2019, 17:49    Post subject:  

@ Sc0ttman:-

Mm... Kinda like Wikipedia, huh? Where any 'Puppian' could alter/edit things, etc., if they felt something needed more detail..?

Only snag with doing that, of course, is that you'd still need an 'editor-in-chief' to oversee the thing on a regular basis, make sure individuals weren't simply mutilating documentation for the sake of it, or just being silly.

Or would even that be automated? I mean, a 'handbook' is actually a good idea, but even so, the individual, original documentation for each & every item would have to be available in the first place, yes? Trouble is, not every developer/coder/whatever gives as much thought as they should, perhaps, to that side of things.....

Nevertheless, it's certainly 'food for thought', indeedy, yes. I just don't really want to ever see Puppy becoming subject to grand proclamations along the lines of Canonical's Shuttleworth, like 'Now, THIS is the direction we see such-and-such going for the forseeable future/next 5 years/whatever, and plans are in the pipeline for this, that & the other...'

That ain't the Puppy I know & love, y'know? The community 'do-ocracy' works very well for us - has until now, certainly - and I, personally, feel we should stick with something similar (if we can, of course).


Mike. Wink

_________________
MY 'PUPPY' PACKAGES

Back to top
View user's profile Send private message 
bigpup


Joined: 11 Oct 2009
Posts: 12999
Location: S.C. USA

PostPosted: Thu 10 Oct 2019, 18:32    Post subject:  

Is this what you are thinking about?

Puppy Help 101
http://www.murga-linux.com/puppy/viewtopic.php?t=69321
smokey01 worked on this for Lucid Puppy 525

It was good for that specific version of Puppy.
However, it will be a constant updating to make it for each specific Puppy version.
I guess it could be a Puppy in general thing.

Download and install the pet to really see what this is.
Run it from menu>Document>Puppy Help 101
Screenshot(1).jpg
 Description   
 Filesize   22.65 KB
 Viewed   162 Time(s)

Screenshot(1).jpg

Screenshot.jpg
 Description   
 Filesize   31.52 KB
 Viewed   144 Time(s)

Screenshot.jpg


_________________
The things they do not tell you, are usually the clue to solving the problem.
When I was a kid I wanted to be older.... This is not what I expected Shocked
YaPI(any iso installer)
Back to top
View user's profile Send private message 
dancytron

Joined: 18 Jul 2012
Posts: 1415

PostPosted: Thu 10 Oct 2019, 19:04    Post subject:  

bigpup wrote:
Is this what you are thinking about?

Puppy Help 101
http://www.murga-linux.com/puppy/viewtopic.php?t=69321
smokey01 worked on this for Lucid Puppy 525

It was good for that specific version of Puppy.
However, it will be a constant updating to make it for each specific Puppy version.
I guess it could be a Puppy in general thing.

Download and install the pet to really see what this is.
Run it from menu>Document>Puppy Help 101


Yes, I remember that and thought that it was excellent.

Another thing might be to have woof generate an .sfs file that has all the man pages that get stripped out with a simple html page front end with a list of links to each one. I might be imagining it, but I think something like that existed at some time.
Back to top
View user's profile Send private message 
bigpup


Joined: 11 Oct 2009
Posts: 12999
Location: S.C. USA

PostPosted: Thu 10 Oct 2019, 19:24    Post subject:  

My eyes glaze over when I look at man pages!
_________________
The things they do not tell you, are usually the clue to solving the problem.
When I was a kid I wanted to be older.... This is not what I expected Shocked
YaPI(any iso installer)
Back to top
View user's profile Send private message 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15556
Location: Paradox Realm

PostPosted: Thu 10 Oct 2019, 22:06    Post subject:  

Quote:
The handbook I make (i'm not gonna rush, work is hectic), will be dead simple, easy to add to, and cover the basics - installation, setup, downloading packages, using the main system tools, etc ..

Sounds wonderful - very useful. Very much look forward to it. Cool I for one need reminding of the stable/innovations/evolving facilities. Very Happy

Our existing wiki documentation is always open for very necessary updating. Cool New blood (hounds) welcome. The software is being updated and server location changed at the moment.
http://wikka.puppylinux.com/UserSettings
http://wikka.puppylinux.com/CategoryTutorial

Using woof-ce produces documentation which is available as 'help' - sure everyone knew that ... Rolling Eyes

@smokies manual contains useful and relevant information. Hopefully a new newsletter will also be announced soon. You lucky dawgs! Write now. Wink
http://www.smokey01.com/newsletters/

Much useful information all over this John Murga hosted Flash admin forum in stickies for example ... Shocked
We even have a slow burner backup forum ... Very Happy
http://puppylinux.info/

Puppy Linux for every Pup
No License Required

_________________
Puppy on Raspberry Pi Release Candidate Cool
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html Very Happy
Back to top
View user's profile Send private message Visit poster's website 
sc0ttman


Joined: 16 Sep 2009
Posts: 2772
Location: UK

PostPosted: Sat 12 Oct 2019, 14:39    Post subject:  

Mike Walsh wrote:
Mm... Kinda like Wikipedia, huh?

No.. Kinda like the CRUX handbook, which I already mentioned.

It was written once, then updated and rebuilt a few times...

Whereas Puppy docs are always from scratch, no pro-forma, no consistent styling, etc, etc ...

Quote:
Where any 'Puppian' could alter/edit things, etc., if they felt something needed more detail..?

Yes and no... It would simply work like this:

Anyone building a puppy using Woof-CE would have the option of running a few extra commands at the end, which took some templates, and generated documentation from them, in the form of HTML files. Simples.

If they wanted different docs or better docs, they can make their own (as now) or improve the templates, then build the docs from those improved templates..

The templates can be updated to include more stuff/fixes, by anyone, by way of pulling down the repo in which they live (should be in woof-ce IMVHO, but whatever), then editing some Markdown files, and doing a Pull Request (PR) on GitHub..

Quote:
Only snag with doing that, of course, is that you'd still need an 'editor-in-chief' to oversee the thing on a regular basis

Firstly, that is entirely the case now... Secondly, no..

You're not getting it. Not on a regular basis - that is the whole point .. if each and every person who ever builds a puppy has some nice documentation templates to use as a starter, then they can auto-build from those...

...and ONLY if they want significantly different (i.e inconsistent) docs from previous puppy releases (a bad idea), then they could still make their own (as everyone does now anyway)..

And any additional info or changes they did make to the templates will be available to the next person who builds a puppy... So they can auto-generate even better docs than before.. with consistency of content, styling, etc

Quote:
make sure individuals weren't simply mutilating documentation for the sake of it, or just being silly.

That basically never happens anyway, and the way GitHub works, that is not a risk at all.

Quote:
a 'handbook' is actually a good idea, but even so, the individual, original documentation for each & every item would have to be available in the first place, yes?

Yes, in the templates ...

Quote:
Trouble is, not every developer/coder/whatever gives as much thought as they should, perhaps, to that side of things.....

Your solution is to let people make up all their own docs from scratch each time, and for there to be no central website at which these live.. Requiring even more thought and attention each time (and a much crappier experience for puppy users, or more to the point, people yet to try Puppy..)

My approach is to provide people with nice templates that generate docs that can be included in Puppy, and can go on a nice website, providing all kinds of nice docs "for free" .. I honestly don't see your objection, you just don't understand it..

This is not some big change in the puppy world..

Quote:
The community 'do-ocracy' works very well for us - has until now, certainly - and I, personally, feel we should stick with something similar (if we can, of course).


Mike. Wink

I know it's a do-ocracy ..

That is why I made Mdsh - it is a MUCH better static site generator than anything inluced in Puppy at the mo, (like pplog, sjpplog, bashblog, shell-cms, etc) and has only Bash, Python and Perl as dependencies..

So it should work in Puppy "out of the box", unlike Jekyll, Gatsby, etc..

Mdsh could be included in Puppy by default, so that Puppy includes a powerful static site generator/blog making thing/doc generator by default (unlike most other distros)..

And unlike those other ones, it can use dynamic markdown to product different HTML pages from a single markdown file.

And it just so happens that Mdsh can already easily generate better blogs (and docs) than anything Puppy currently has installed by default... If people want to generate them ... it just needs someone to re-write the docs we have in markdown, put them in a single place, then run `rebuild file.md > file.html`...

_________________
Pkg, mdsh, Woofy, Akita, VLC-GTK, Search

Last edited by sc0ttman on Sat 12 Oct 2019, 15:31; edited 5 times in total
Back to top
View user's profile Send private message 
Display posts from previous:   Sort by:   
Page 1 of 2 [20 Posts]   Goto page: 1, 2 Next
Post new topic   Reply to topic View previous topic :: View next topic
 Forum index » Taking the Puppy out for a walk » Suggestions
Jump to:  

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum


Powered by phpBB © 2001, 2005 phpBB Group
[ Time: 0.0807s ][ Queries: 12 (0.0085s) ][ GZIP on ]