Better Documentation
Better 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/$DI ... N/Homepage
http://wiki.puppylinux.org/Releases/$DI ... ION/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)...
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/$DI ... N/Homepage
http://wiki.puppylinux.org/Releases/$DI ... ION/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)...
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
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":
Then just run:
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!
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?
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: Select all
# Some header
## Puppy version <?bash echo $DISTRO_NAME ;?>
Code: Select all
source /etc/DISTRO_SPECS
rebuild foo.mdsh > ${DISTRO_NAME}.html
![Smile :)](./images/smilies/icon_smile.gif)
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?
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
- Lobster
- Official Crustacean
- Posts: 15522
- Joined: Wed 04 May 2005, 06:06
- Location: Paradox Realm
- Contact:
It might be Mick Armadio ... ? Used to be raffy?Who is the maintainer of PuppyLinux.com?
This page is a little out of date
![Embarassed :oops:](./images/smilies/icon_redface.gif)
http://wikka.puppylinux.com/PuppyOrganization
Well done on the documenting initiative
![Cool 8)](./images/smilies/icon_cool.gif)
Puppy doacracy
What you do, gets done
If you want to change http://puppylinux.com issue a pull request at https://github.com/puppylinux-woof-CE/p ... .github.io
We are all the maintainers.
We are all the maintainers.
Puppy Linux Blog - contact me for access
- Mike Walsh
- Posts: 6351
- Joined: Sat 28 Jun 2014, 12:42
- Location: King's Lynn, UK.
I don't see what the objection is here...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.....
(*shrug*)
Mike.
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..
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
- Mike Walsh
- Posts: 6351
- Joined: Sat 28 Jun 2014, 12:42
- Location: King's Lynn, UK.
@ 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 :wink:](./images/smilies/icon_wink.gif)
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 :wink:](./images/smilies/icon_wink.gif)
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
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
- Attachments
-
- Screenshot(1).jpg
- (22.65 KiB) Downloaded 230 times
-
- Screenshot.jpg
- (31.52 KiB) Downloaded 216 times
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 :shock:](./images/smilies/icon_eek.gif)
YaPI(any iso installer)
When I was a kid I wanted to be older.... This is not what I expected
![Shocked :shock:](./images/smilies/icon_eek.gif)
YaPI(any iso installer)
Yes, I remember that and thought that it was excellent.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
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.
- Lobster
- Official Crustacean
- Posts: 15522
- Joined: Wed 04 May 2005, 06:06
- Location: Paradox Realm
- Contact:
Sounds wonderful - very useful. Very much look forward to it.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 ..
![Cool 8)](./images/smilies/icon_cool.gif)
![Very Happy :D](./images/smilies/icon_biggrin.gif)
Our existing wiki documentation is always open for very necessary updating.
![Cool 8)](./images/smilies/icon_cool.gif)
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 :roll:](./images/smilies/icon_rolleyes.gif)
@smokies manual contains useful and relevant information. Hopefully a new newsletter will also be announced soon. You lucky dawgs! Write now.
![Wink :wink:](./images/smilies/icon_wink.gif)
http://www.smokey01.com/newsletters/
Much useful information all over this John Murga hosted Flash admin forum in stickies for example ...
![Shocked :shock:](./images/smilies/icon_eek.gif)
We even have a slow burner backup forum ...
![Very Happy :D](./images/smilies/icon_biggrin.gif)
http://puppylinux.info/
Puppy Linux for every Pup
No License Required
No.. Kinda like the CRUX handbook, which I already mentioned.Mike Walsh wrote:Mm... Kinda like Wikipedia, huh?
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 ...
Yes and no... It would simply work like this:Where any 'Puppian' could alter/edit things, etc., if they felt something needed more detail..?
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..
Firstly, that is entirely the case now... Secondly, no..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
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
That basically never happens anyway, and the way GitHub works, that is not a risk at all.make sure individuals weren't simply mutilating documentation for the sake of it, or just being silly.
Yes, in the templates ...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?
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..)Trouble is, not every developer/coder/whatever gives as much thought as they should, perhaps, to that side of things.....
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..
I know it's a do-ocracy ..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.
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`...
Last edited by sc0ttman on Sat 12 Oct 2019, 19:31, edited 5 times in total.
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
^ So that, and various other things (puppy site, wiki, github, etc) would be a good place to get the docs/info that we need .. Saved into mdsh template/markdown files ..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
Like I said .. I will generate a couple of little demo handbooks for a couple of different pups, so people can see how easy it should be to document lots of puppy releases with nice, consistent, online docs..
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
@sc0ttman
I am a firm believer that Pkg system should be immediately included in stock factory fresh Puppy Linux variants.
I have created a shell script for WeeDog (Void Linux ) that will completely install ZoneMinder fully automated. The goal originally was to build such a script for Puppy Linux Bionic (32 & 64 bit) but there was always some problem installing packages and dependencies needed for a functional LAMP or LHMP and the zoneminder package. But now Pkg manager makes this possible and I hope to have a working example for Bionic soon. With Void the xbps package manager is outstanding and and was written from scratch and the OS is built around the package manager. Adding Pkg to Puppy Linux brings a very powerful manager into play. Just being able to add the 3rd party ZoneMinder repository made me a immediate fan of Pkg. I am very appreciative of the work, thought and actions that bought the program to production level.
I do use mdsh more now in the process of writing all the documentation that goes along with auto build scripts and customized plugins that are involved with the FirstRib -WeeDog project. The hardest part is producing clear documentation for build recipes and how-to's that go along with all of it. In WeeDog I use cutemarked and I for one am glad that mdsh for Puppy Linux gives me a similar tool.
I see more and more documentation being generated using this platform : https://readthedocs.org/
**
I am a firm believer that Pkg system should be immediately included in stock factory fresh Puppy Linux variants.
I have created a shell script for WeeDog (Void Linux ) that will completely install ZoneMinder fully automated. The goal originally was to build such a script for Puppy Linux Bionic (32 & 64 bit) but there was always some problem installing packages and dependencies needed for a functional LAMP or LHMP and the zoneminder package. But now Pkg manager makes this possible and I hope to have a working example for Bionic soon. With Void the xbps package manager is outstanding and and was written from scratch and the OS is built around the package manager. Adding Pkg to Puppy Linux brings a very powerful manager into play. Just being able to add the 3rd party ZoneMinder repository made me a immediate fan of Pkg. I am very appreciative of the work, thought and actions that bought the program to production level.
I do use mdsh more now in the process of writing all the documentation that goes along with auto build scripts and customized plugins that are involved with the FirstRib -WeeDog project. The hardest part is producing clear documentation for build recipes and how-to's that go along with all of it. In WeeDog I use cutemarked and I for one am glad that mdsh for Puppy Linux gives me a similar tool.
I see more and more documentation being generated using this platform : https://readthedocs.org/
**
Cheers.. Once we finally fix the slow dep resolution, I think it will be a nice thing to have..rockedge wrote:@sc0ttman
I am a firm believer that Pkg system should be immediately included in stock factory fresh Puppy Linux variants.
Thanks very much.. Maybe you could use Pkg is auto-create an SFS of the zone minder stuff, then use Pkg to create a repo at which you host it... (Free hosting at github for repos less than 1GB IIRC)...Adding Pkg to Puppy Linux brings a very powerful manager into play. Just being able to add the 3rd party ZoneMinder repository made me a immediate fan of Pkg. I am very appreciative of the work, thought and actions that bought the program to production level.
mdsh is still in alpha stages I reckon ... But should work fine (slow but fine) if you don't try anything too exoticI do use mdsh more now in the process of writing all the documentation that goes along with auto build scripts and customized plugins that are involved with the FirstRib -WeeDog project.
![Wink ;)](./images/smilies/icon_wink.gif)
...hopefully...In WeeDog I use cutemarked and I for one am glad that mdsh for Puppy Linux gives me a similar tool.
I just made, and attached a super simple html shell/example which kinda rips off the readthedocs layout/style (a bit) .. if you wanted it..I see more and more documentation being generated using this platform : https://readthedocs.org/
I might use it as a "documentation" theme in mdsh ..
![Image](https://i.imgur.com/ZIa8PvJ.png)
- Attachments
-
- index.html.gz
- fake .gz, rename..
- (3.21 KiB) Downloaded 201 times
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
a more consistent timeline of releases
We should have docs online somewhere that tell users about intended "official release" cycles,
which versions are "supported" and which are not..
This requires us to work out what our policy actually is.
Here are some suggestions.. Discuss...
Policy on "Official releases":
I say we try to release an official release every two years.
A fairly fixed two year release cycle would be good:
- predictable for users
- gives us some (fairly) fixed release deadlines / timelines
- helps to keep puppy current and up to date
Each official release could/should have as a "definition of done":
- 32 bit version
- 64 bit version
- passed user testing:
-- works with frugal install
-- works with full install
-- boots to desktop
-- working on target devices:
---- audio
---- video
---- ethernet
---- wifi
---- samba
---- printing
---- bluetooth
---- mounted drives (exfat, ntfs, fat32, f2fs)
It's no secret I think we should offer different "flavours" on release too - JWM, LXDE,
Xfce, etc - all at the same time. But leave that for now..
I guess ARM based Pups would be irregular or "not fit" in many ways, but hopefully
with 01mickos work, when could endevour to always include an "official" ARM release along with
the 32 and 64 bit official releases.
Policy on "Community Editions"
A "community edition" could/should always just be a re-release of an official version,
about a year later, with latest Woof-CE fixes, forum contributions, and a few more apps
installed by default.
Community Editions could differentiate themselves from "official" releases in that they have:
- extra "puppy-xxx-contrib" repo installed by default, (containing packages made by users after the official release)
- latest woof-ce codebase
- updated program versions and libs
- manual bug fixes & tweaks from end-users, testers, forum
- more default programs added
- therefore, a bit more "user friendly" than a regular Puppy
The extra repo and programs would be nice to add as after an official release cos
users often create lots of great PETs and SFS packages after a Puppy is released,
and these can easily be added to a user contributed "contrib" repo, which get included
in a CE version by default (using Pkg, anyway
).
They could be the "conventions" that make CE releases stand out from regular releases.
The timeline
So, every two years (or so) there would be an official release.
There would (usually) be a "community edition" of the official release, one year later,
to extend it's life a little.
.. This would be a nice schedule, because:
- it's reliable, predicable
- easier to work out what new releases are coming
- makes working out which versions of "official" and which are not MUCH easier
- users can stick with official releases, changing every two years
- users can stick with CE releases, changing every two years
- users can update every year if they wish, from official -> CE -> official
. Just a thought, I know it's like herding cats here... But if we had a calendar or intended
calendar, then devs can try to plan ahead together a little easier.
About which versions are "supported" and which are not:
A version still being "supported" means that it is still receiving updates/bug fixes of some kind,
or has a active forum thread.
Anything older than 4 years, we don't support - we don't make new packages for it, back port
bug fixes to it, etc - we simply forward users of these older versions to forum threads.
NOTE: many of these suggestions are already somewhat puppy traditions or informal conventions ..
Maybe we can hash them out and create some docs somewhere that make it all a bit
clearer for everyone?
which versions are "supported" and which are not..
This requires us to work out what our policy actually is.
Here are some suggestions.. Discuss...
Policy on "Official releases":
I say we try to release an official release every two years.
A fairly fixed two year release cycle would be good:
- predictable for users
- gives us some (fairly) fixed release deadlines / timelines
- helps to keep puppy current and up to date
Each official release could/should have as a "definition of done":
- 32 bit version
- 64 bit version
- passed user testing:
-- works with frugal install
-- works with full install
-- boots to desktop
-- working on target devices:
---- audio
---- video
---- ethernet
---- wifi
---- samba
---- printing
---- bluetooth
---- mounted drives (exfat, ntfs, fat32, f2fs)
It's no secret I think we should offer different "flavours" on release too - JWM, LXDE,
Xfce, etc - all at the same time. But leave that for now..
I guess ARM based Pups would be irregular or "not fit" in many ways, but hopefully
with 01mickos work, when could endevour to always include an "official" ARM release along with
the 32 and 64 bit official releases.
Policy on "Community Editions"
A "community edition" could/should always just be a re-release of an official version,
about a year later, with latest Woof-CE fixes, forum contributions, and a few more apps
installed by default.
Community Editions could differentiate themselves from "official" releases in that they have:
- extra "puppy-xxx-contrib" repo installed by default, (containing packages made by users after the official release)
- latest woof-ce codebase
- updated program versions and libs
- manual bug fixes & tweaks from end-users, testers, forum
- more default programs added
- therefore, a bit more "user friendly" than a regular Puppy
The extra repo and programs would be nice to add as after an official release cos
users often create lots of great PETs and SFS packages after a Puppy is released,
and these can easily be added to a user contributed "contrib" repo, which get included
in a CE version by default (using Pkg, anyway
![Wink ;)](./images/smilies/icon_wink.gif)
They could be the "conventions" that make CE releases stand out from regular releases.
The timeline
So, every two years (or so) there would be an official release.
There would (usually) be a "community edition" of the official release, one year later,
to extend it's life a little.
.. This would be a nice schedule, because:
- it's reliable, predicable
- easier to work out what new releases are coming
- makes working out which versions of "official" and which are not MUCH easier
- users can stick with official releases, changing every two years
- users can stick with CE releases, changing every two years
- users can update every year if they wish, from official -> CE -> official
. Just a thought, I know it's like herding cats here... But if we had a calendar or intended
calendar, then devs can try to plan ahead together a little easier.
About which versions are "supported" and which are not:
A version still being "supported" means that it is still receiving updates/bug fixes of some kind,
or has a active forum thread.
Anything older than 4 years, we don't support - we don't make new packages for it, back port
bug fixes to it, etc - we simply forward users of these older versions to forum threads.
NOTE: many of these suggestions are already somewhat puppy traditions or informal conventions ..
Maybe we can hash them out and create some docs somewhere that make it all a bit
clearer for everyone?
[b][url=https://bit.ly/2KjtxoD]Pkg[/url], [url=https://bit.ly/2U6dzxV]mdsh[/url], [url=https://bit.ly/2G49OE8]Woofy[/url], [url=http://goo.gl/bzBU1]Akita[/url], [url=http://goo.gl/SO5ug]VLC-GTK[/url], [url=https://tiny.cc/c2hnfz]Search[/url][/b]
- Lobster
- Official Crustacean
- Posts: 15522
- Joined: Wed 04 May 2005, 06:06
- Location: Paradox Realm
- Contact:
Have added the information here:
http://wikka.puppylinux.com/ProjectStatement
![Cool 8)](./images/smilies/icon_cool.gif)
Do or Do not. There is only Try Puppy.
Puppy Master Yoda
http://wikka.puppylinux.com/ProjectStatement
![Cool 8)](./images/smilies/icon_cool.gif)
Do or Do not. There is only Try Puppy.
Puppy Master Yoda