Puppy documentation needs updated or replaced

Issues and / or general discussion relating to Puppy

Moderator: Forum moderators

Post Reply
User avatar
bigpup
Moderator
Posts: 6929
Joined: Tue Jul 14, 2020 11:19 pm
Location: Earth, South Eastern U.S.
Has thanked: 897 times
Been thanked: 1508 times

Puppy documentation needs updated or replaced

Post by bigpup »

This will be the topic to try and fix this!

All the documentation for Puppy Linux is getting very outdated.

All the files are the ones in /usr/share/doc

Only a few of them have had any edits to have them provide updated info.

user1234 is person working on this.

Any info on what still needs worked on he is providing in the last pages of this topic.

Remember, we are Puppy.
What it is, will be controlled, by what we make it!

The things you do not tell us, are usually the clue to fixing the problem.
When I was a kid, I wanted to be older.
This is not what I expected :o

User avatar
Wiz57
Moderator
Posts: 562
Joined: Fri Dec 13, 2019 3:54 pm
Location: Chickasha, OK USA
Has thanked: 77 times
Been thanked: 114 times

Re: Puppy documentation needs updated or replaced

Post by Wiz57 »

What "format" would be a preference? Currently most of the documents are in HTML format, requiring some at least minimal
web browser or HTML viewer (do these still exist? Last I used was in MS DOS 6.22 days.) Perhaps if the format was changed to
say RTF (Rich Text File) then most any document editor could display them? Or plain text? Perhaps bog standard DOC (not
DOCX or other proprietary format)?
Wiz

Signature available upon request

williwaw
Posts: 1910
Joined: Tue Jul 14, 2020 11:24 pm
Has thanked: 168 times
Been thanked: 354 times

Re: Puppy documentation needs updated or replaced

Post by williwaw »

can woof-ce build the capability to view a man page?

williams2
Posts: 1061
Joined: Sat Jul 25, 2020 5:45 pm
Been thanked: 304 times

Re: Puppy documentation needs updated or replaced

Post by williams2 »

an woof-ce build the capability to view a man page?

I think the dev sfs file has tools to work with man pages.
I'm not sure whether you can read man pages with the dev sfs file loaded.

The software to read man files can be installed, like any other software, so yes, I think woof could be configured to include the man software files.

And man2html is often installed in the base sfs file(s).
I don't remember if it works OOTB.

dimkr
Posts: 2398
Joined: Wed Dec 30, 2020 6:14 pm
Has thanked: 53 times
Been thanked: 1182 times

Re: Puppy documentation needs updated or replaced

Post by dimkr »

williwaw wrote: Sun Nov 06, 2022 3:17 am

can woof-ce build the capability to view a man page?

Yes, but AFAIK Vanilla Dpup is the only Puppy that takes advantage of that.

Why not replace the "help" menu entry with a link to viewforum.php?f=184?

User avatar
mikeslr
Posts: 2944
Joined: Mon Jul 13, 2020 11:08 pm
Has thanked: 178 times
Been thanked: 905 times

Re: Puppy documentation needs updated or replaced

Post by mikeslr »

dimkr +1.

Then the only 'internal' help file you'd need is one explaining 'how to obtain a web-browser' if one isn't already provided.

Fun isn't work and doing whatever you want with any Puppy is fun; even explaining about what you've done. Otherwise writing documentations is hard work; re-writing them is even harder.

User avatar
bigpup
Moderator
Posts: 6929
Joined: Tue Jul 14, 2020 11:19 pm
Location: Earth, South Eastern U.S.
Has thanked: 897 times
Been thanked: 1508 times

Re: Puppy documentation needs updated or replaced

Post by bigpup »

Why not replace the "help" menu entry with a link to the puppy forum?

That would work for what information is provided their.

If you had a working web browser and an established Internet connection.

As the menu -> Help now is.

Only need a working browser.

It accesses a file that can be read, with out having a network Internet connection.

All the links on it will bring up other files that are in usr/share/doc

---------------------------------------------------------------------------------------------------------------------------------------------

Puppy OS info and help files, were originally made in HTM and HTML type, so that they could have clickable links to other files or web sites.

-------------------------------------------------------------------------------------------------------------------------------------------------

A lot of the files have web site links that are pointing to old Puppy forum or Barry K specific web sites that no longer exist.
Correcting those should not too hard.

The things you do not tell us, are usually the clue to fixing the problem.
When I was a kid, I wanted to be older.
This is not what I expected :o

Clarity
Posts: 3778
Joined: Fri Jul 24, 2020 10:59 pm
Has thanked: 1600 times
Been thanked: 513 times

Re: Puppy documentation needs updated or replaced

Post by Clarity »

This thread is an excellent request. To get more views and contributions, should this be placed in this forum area verses here in this Users area?

If this thread is moved to the General area, please ALSO remove this post!

User avatar
wizard
Posts: 1935
Joined: Sun Aug 09, 2020 7:50 pm
Has thanked: 2593 times
Been thanked: 664 times

Re: Puppy documentation needs updated or replaced

Post by wizard »

If you have not looked at the HELP files for Friendly-Fossa64 (a remaster of Fossapup64 9.5), attached is a link (to help files only). https://sourceforge.net/projects/wizard ... z/download

The files are in .DOC format created with Libreoffice Writer and can be "viewed" with Abiword. These could easily be modified to work with a Fossapup64-9.6-CE. Compared to the "native" HTML help files, they cover additional topics to help new user and they include graphic images. They are larger than the native files, but are still only 1.3 mb total.

The existing files do include references to programs that are not part of Fossapup64 9.5 and would need to be changed accordingly if these were not in Fossapup64-9.6-CE

Also included is the document, Programs_Installed.xls, which gives the user some idea of the wide variety of tools available. I would suggest including and expanding this list to all programs in the menus. This is one of Puppy's strengths OOTB and deserves an icon on the desktop.

Thanks
wizard

Big pile of OLD computers

williams2
Posts: 1061
Joined: Sat Jul 25, 2020 5:45 pm
Been thanked: 304 times

Re: Puppy documentation needs updated or replaced

Post by williams2 »

If you are looking for documentation about kernel boot parameters,

see viewtopic.php?t=5818

This forum > Board index > General Information > Getting Started and System Requirements > How Puppy Linux Works.

User avatar
mikewalsh
Moderator
Posts: 6115
Joined: Tue Dec 03, 2019 1:40 pm
Location: King's Lynn, UK
Has thanked: 781 times
Been thanked: 1952 times

Re: Puppy documentation needs updated or replaced

Post by mikewalsh »

Once again, I notice nobody is in fact volunteering.....but of course, lots of people are posting with suggestions for somebody else to do the actual work.

Why is that that it always seems to fall to the same small "pool" of members to carry everybody else, hmm? Surely the rest of the community aren't quite that helpless, are they?

Mike. :roll:

User avatar
puppy_apprentice
Posts: 690
Joined: Tue Oct 06, 2020 8:43 pm
Location: land of bigos and schabowy ;)
Has thanked: 5 times
Been thanked: 114 times

Re: Puppy documentation needs updated or replaced

Post by puppy_apprentice »

Automated conversion forum articles to PDF:
viewtopic.php?p=65919#p65919
Every Puppy has PDF viewer.

dimkr
Posts: 2398
Joined: Wed Dec 30, 2020 6:14 pm
Has thanked: 53 times
Been thanked: 1182 times

Re: Puppy documentation needs updated or replaced

Post by dimkr »

It doesn't matter if the help files are converted to .odt, .pdf or whatever if the content is useless or even misleading :roll:

User avatar
puppy_apprentice
Posts: 690
Joined: Tue Oct 06, 2020 8:43 pm
Location: land of bigos and schabowy ;)
Has thanked: 5 times
Been thanked: 114 times

Re: Puppy documentation needs updated or replaced

Post by puppy_apprentice »

dimkr wrote: Wed Nov 09, 2022 5:17 pm

It doesn't matter if the help files are converted to .odt, .pdf or whatever if the content is useless or even misleading :roll:

But those articles are up to date and will be revised if necessary?
viewforum.php?f=184
So they could be easily converted to PDF Manual via Prince.

User avatar
user1234
Posts: 414
Joined: Sat Feb 26, 2022 5:48 am
Location: Somewhere on earth
Has thanked: 155 times
Been thanked: 90 times

Re: Puppy documentation needs updated or replaced

Post by user1234 »

So @bigpup, I'll try to help in the documentation stuff, wherever my knowledge applies.

Still I need that you tell where the documentation files are (in a github repo or in some specific puppy versions)? And how would you implement the changes (changes for to-be-built puppies or the ones which are already there)? If you want to implement them in the already built puppies, then how are you gonna make them available to the users?

PuppyLinux 🐾 gives new life to old computers ✨

dimkr
Posts: 2398
Joined: Wed Dec 30, 2020 6:14 pm
Has thanked: 53 times
Been thanked: 1182 times

Re: Puppy documentation needs updated or replaced

Post by dimkr »

puppy_apprentice wrote: Wed Nov 09, 2022 5:34 pm

So they could be easily converted to PDF Manual via Prince.

Why convert the topics in this forum to PDF instead of changing the Help menu entry so it points to this forum?

If every Puppy ships with a .pdf snapshot of the current forum contents, the user is stuck with old documentation after a while. Also, .pdf files can be big and they're binary (less compressible).

user1234 wrote: Wed Nov 09, 2022 5:49 pm

Still I need that you tell where the documentation files are

https://github.com/puppylinux-woof-CE/w ... /share/doc

User avatar
puppy_apprentice
Posts: 690
Joined: Tue Oct 06, 2020 8:43 pm
Location: land of bigos and schabowy ;)
Has thanked: 5 times
Been thanked: 114 times

Re: Puppy documentation needs updated or replaced

Post by puppy_apprentice »

dimkr wrote: Wed Nov 09, 2022 6:36 pm

Why convert the topics in this forum to PDF instead of changing the Help menu entry so it points to this forum?

Sometimes there are situations that you do not have access to the Internet or the forum is slow.

dimkr wrote: Wed Nov 09, 2022 6:36 pm

Also, .pdf files can be big and they're binary (less compressible).

Puppy is bigger and bigger so few MB more isn't problem (or is?). I will try to make a PDF with those articles (in the weekend). I think that it will not be bigger that 10MB.

User avatar
bigpup
Moderator
Posts: 6929
Joined: Tue Jul 14, 2020 11:19 pm
Location: Earth, South Eastern U.S.
Has thanked: 897 times
Been thanked: 1508 times

Re: Puppy documentation needs updated or replaced

Post by bigpup »

Size of Puppy is still something to consider.

Remember that all of Puppy gets loaded into memory.

There are still people around the world, that use computers with low amounts of memory, in them.

Are these pdf versions going to have clickable links?

Reinventing the wheel, making it bigger, is only a good idea, if it really needs to be bigger.

These documentation files, have been around for years, they work, and are integrated in Puppy program code.

What is needed is only making changes to the information in them, so it is current info.

Pick a file to look at.

Read it.

Change what you think needs changed.

Should be able to attach it to a post in this topic, so others can review it.

Just to have another set of eyes looking at what is submitted.

Then it can be elevated to placement into the repository at Woof -CE

No one is asking for just one person to work on all of these documentation files, unless you just want to!

The things you do not tell us, are usually the clue to fixing the problem.
When I was a kid, I wanted to be older.
This is not what I expected :o

User avatar
puppy_apprentice
Posts: 690
Joined: Tue Oct 06, 2020 8:43 pm
Location: land of bigos and schabowy ;)
Has thanked: 5 times
Been thanked: 114 times

Re: Puppy documentation needs updated or replaced

Post by puppy_apprentice »

bigpup wrote: Wed Nov 09, 2022 7:23 pm

Are these pdf versions going to have clickable links?

There is an example file, you can check:
viewtopic.php?t=6714
or directly: Manual.pdf

Ok I don't insist. But from the developer's point of view it will be easier to make such an manual. It will be an automatic method.

bigpup wrote: Wed Nov 09, 2022 7:23 pm

There are still people around the world, that use computers with low amounts of memory, in them.

You can attach this PDF to the main directory of CD/ISO (or in Help directory) it doesn't have to be in Puppy system file.

On the other hand, the downloaded file you can use when you want. In Africa there may be problems with access to the Internet on demand.

bigpup wrote: Wed Nov 09, 2022 7:23 pm

No one is asking for just one person to work on all of these documentation files, unless you just want to!

I offer to convert and prepare Prince so that anyone can do it. I will not edit these forum articles.

User avatar
wizard
Posts: 1935
Joined: Sun Aug 09, 2020 7:50 pm
Has thanked: 2593 times
Been thanked: 664 times

Re: Puppy documentation needs updated or replaced

Post by wizard »

@mikewalsh

You are right, most of the time we get a lot of talk and not much action. However, in this case, there are some added obstacles.
1. Most of the members don't use github
2. On the chance that they follow the link to the existing help files and figure out they can't click on the Help directory, then click on
an actual file they find themselves looking at a page of HTML code with no obvious way to download anything.

The fact is few members know how and are willing to deal with the files in HTML format.

So here's my point of view. The legacy help files are in HTML format and frankly are quite general in nature. New users need and benefit
from help files that show images and include step by step instructions. You can certainly do that in HTML, but it starts to get way more complicated. Using HTML does give you the advantage of using links, but linking to external sources has a great risk of having dead links. A prime example is the current help files in which the large majority of the links are dead.

PDF format has been discussed, but would require maintaining a editable "master" and it presents issues for translation to other languages.

The issue of size should not be a factor between HTML, PDF, or .DOC since it is quite small.

If we're going to up our game, we need to change to a format that can use embed graphics and that is easy to create and maintain by the members.

I went through all of this exercise when formulating the help files for Friendly-Fossa64 and concluded that the .DOC format best met the needs and criteria of "easy to create and maintain"

wizard

Big pile of OLD computers

User avatar
mikewalsh
Moderator
Posts: 6115
Joined: Tue Dec 03, 2019 1:40 pm
Location: King's Lynn, UK
Has thanked: 781 times
Been thanked: 1952 times

Re: Puppy documentation needs updated or replaced

Post by mikewalsh »

@wizard :-

I agree that HTML is far from intuitive for non-users. I've never used it myself, but my assumption is that the user would:-

  • Copy the page of HTML code, then

  • Open something like Kompozer, BlueGriffon or even the built-in editor in something like SeaMonkey, then paste the contents of the clipboard into an empty document. After that, well.....I don't know, exactly, but I believe you can make that HTML code display as a "finished" webpage to see what it looks like.

I assume you can then edit it, and finish up by reversing the process to convert it back into HTML code again. I'm probably wrong, and more than happy to be corrected... :D

------------------------------

(Thinking about it, hmmm; creating help documentation for one's own 'product' is a labour of love. Even I've done that with much of my more recent stuff. But producing extensive documentation for every aspect of Puppy itself - to be usable by the entire community, from noobs to veterans, if necessary in multiple languages.....mikeslr has hit the nail on the head. Puppy is fun. Creating valid documentation that everyone is happy with is just plain hard work. It's no wonder nobody's volunteering.) :|

Mike. ;)

User avatar
wizard
Posts: 1935
Joined: Sun Aug 09, 2020 7:50 pm
Has thanked: 2593 times
Been thanked: 664 times

Re: Puppy documentation needs updated or replaced

Post by wizard »

@mikewalsh
Fair analysis, but give it a real try. Pick a file with some dead links, see if you can fix them, then add a couple of images AND then test it in 3 or 4 browsers to see if it renders correctly. Next, upload back and be sure your images (which are external) and their links will all still work when installed in the Puppy file system :lol:

I can tell you how to do a .DOC help file in about one paragraph, it will be WYSIWYG, single file, no code, and just about everyone already knows how to use a word processing programg :mrgreen:

Just sayin

wizard

Big pile of OLD computers

User avatar
bigpup
Moderator
Posts: 6929
Joined: Tue Jul 14, 2020 11:19 pm
Location: Earth, South Eastern U.S.
Has thanked: 897 times
Been thanked: 1508 times

Re: Puppy documentation needs updated or replaced

Post by bigpup »

The legacy help files are in HTML format and frankly are quite general in nature.

The general in nature is because the actual program you may use will have it's own help.

Example:
Most Puppy versions have 3 different programs that could be used for a network connection.

The things you do not tell us, are usually the clue to fixing the problem.
When I was a kid, I wanted to be older.
This is not what I expected :o

User avatar
mikewalsh
Moderator
Posts: 6115
Joined: Tue Dec 03, 2019 1:40 pm
Location: King's Lynn, UK
Has thanked: 781 times
Been thanked: 1952 times

Re: Puppy documentation needs updated or replaced

Post by mikewalsh »

wizard wrote: Wed Nov 09, 2022 11:39 pm

@mikewalsh
Fair analysis, but give it a real try. Pick a file with some dead links, see if you can fix them, then add a couple of images AND then test it in 3 or 4 browsers to see if it renders correctly. Next, upload back and be sure your images (which are external) and their links will all still work when installed in the Puppy file system :lol:

I can tell you how to do a .DOC help file in about one paragraph, it will be WYSIWYG, single file, no code, and just about everyone already knows how to use a word processing programg :mrgreen:

Just sayin

wizard

@wizard :-

I've got more than enough on my plate, maintaining all the contributions I have made over the years. That's one side of things I have zero interest in getting involved with....

Sorry an' all that.

Mike. :|

User avatar
user1234
Posts: 414
Joined: Sat Feb 26, 2022 5:48 am
Location: Somewhere on earth
Has thanked: 155 times
Been thanked: 90 times

Re: Puppy documentation needs updated or replaced

Post by user1234 »

I have just created a 'draft' PR here. I have given information for which files I have updated. I have kept this as a draft to signify that there can be more things which I can update, just will have to see. That is likely all I will be able to contribute today, I suppose. But for sure will continue the work later on.

And yes, @mikewalsh, I have included links to few of your portable apps. I hope you're completely okay with this, are you?

PuppyLinux 🐾 gives new life to old computers ✨

User avatar
bigpup
Moderator
Posts: 6929
Joined: Tue Jul 14, 2020 11:19 pm
Location: Earth, South Eastern U.S.
Has thanked: 897 times
Been thanked: 1508 times

Re: Puppy documentation needs updated or replaced

Post by bigpup »

@user1234

Thanks for working on these documents.

Overall very good work!

I suggest whatever you come up with, please post it here first.
This will allow others to look it over before submitting it to Woof -CE

I looked at your devx.htm

I found one link that was no good.

Also have a suggestion for a small change or addition to the information.

I have found, over the years of producing info about Puppy Linux, and how to do things in it.

I am happy to have others, that have looked it over, offer suggestions or point out something I missed or stated wrong.

It is amazing what others see that you do not!

The things you do not tell us, are usually the clue to fixing the problem.
When I was a kid, I wanted to be older.
This is not what I expected :o

User avatar
mikewalsh
Moderator
Posts: 6115
Joined: Tue Dec 03, 2019 1:40 pm
Location: King's Lynn, UK
Has thanked: 781 times
Been thanked: 1952 times

Re: Puppy documentation needs updated or replaced

Post by mikewalsh »

@user1234 :-

user1234 wrote: Thu Nov 10, 2022 10:45 am

I have just created a 'draft' PR here. I have given information for which files I have updated. I have kept this as a draft to signify that there can be more things which I can update, just will have to see. That is likely all I will be able to contribute today, I suppose. But for sure will continue the work later on.

And yes, @mikewalsh , I have included links to few of your portable apps. I hope you're completely okay with this, are you?

No worries, mate. Feel free.....they are provided for all to enjoy..! :thumbup:

So.....how do you actually "view" these?

--------------------------

@bigpup :- That's entirely due to being too close to whatever it is you're doing.....or in plain English, "can't see the wood for the trees"! :lol:

Mike. ;)

User avatar
wizard
Posts: 1935
Joined: Sun Aug 09, 2020 7:50 pm
Has thanked: 2593 times
Been thanked: 664 times

Re: Puppy documentation needs updated or replaced

Post by wizard »

@mikewalsh

You are correct and are one of my Puppy Heros for all you contribute :thumbup2: . Wasn't my aim to get you off course. It's Just an example of wizard's rule #6 "Everything that should be easy, isn't"

wizard

Last edited by wizard on Thu Nov 10, 2022 2:45 pm, edited 2 times in total.

Big pile of OLD computers

User avatar
mikewalsh
Moderator
Posts: 6115
Joined: Tue Dec 03, 2019 1:40 pm
Location: King's Lynn, UK
Has thanked: 781 times
Been thanked: 1952 times

Re: Puppy documentation needs updated or replaced

Post by mikewalsh »

wizard wrote: Thu Nov 10, 2022 2:38 pm

@mikewalsh

You are correct and are one of my Puppy Heros for all you contribute :thumbup2: . Wasn't my aim to get you off course. It's Just an example of wizard's rule #6 "Everything that should be easy, isn't"

wizard

^^^ :lol: :lol: :lol:

Mike. ;)

User avatar
wizard
Posts: 1935
Joined: Sun Aug 09, 2020 7:50 pm
Has thanked: 2593 times
Been thanked: 664 times

Re: Puppy documentation needs updated or replaced

Post by wizard »

@mikewalsh

So.....how do you actually "view" these?

And another example :D

Big pile of OLD computers

Post Reply

Return to “Users”