Puppy documentation needs updated or replaced

[williwaw]

@bigpup

my pburn help must not be like your pburn help, or perhaps we are using different browsers?
firefox here

I have not seen the functionality you describe in your edit either. are you editing in a html composer app? I see a change in line 138, target="_self">⇑</a> from target="_self">&uArr;</a> , but not sure what it is supposed to do different.

Do you know how I can make the scroll back button return to the TOC rather than to the top of the page? If the preface or heading was larger, one would have to scroll down to the TOC after using the button.

[bigpup]

I used Seamonkey browser composer to edit your pupindex.html
All I did was add more information statements to the Introduction section.

That change to line 138 could be something Seamonkey composer did.
Maybe a setting in it did this.
There are a lot of default settings that can be set in it.
Editing, adding, and moving text around, changing the clickable links target web sites, is about all I have tried to do in it.

Strange you are not seeing what I am or maybe you are misunderstanding me.

Here in these images I am looking at my edited pupindex.html using Firefox browser.

This is what I see when the pupindex.html is first opened.

Screenshot(1).jpg (70.78 KiB) Viewed 1355 times

.
After clicking the introduction in the Table of Contents, it goes to introduction section and looks like this:

Screenshot(2).jpg (101.26 KiB) Viewed 1355 times

.
all that shows on page is the introduction and the info in it.
To see more you have to scroll down.
This is because there is too much to show, without scrolling down to see it all.
So it fills the complete browser window screen and all you see is the introduction section.
I am not saying all it will scroll is the introduction section.
If you keep scrolling, it will start to display the other sections of the page. Scrolling is still scrolling down the page.

The return to top arrow is there on the lower right side of the displayed page and stays there as you scroll down to show more.
Click on it and it goes back to top showing the beginning and the Table of Contents.

[williwaw]

your described behavior is consistent with mine. I thought your edit somehow accomplished what you wished for earlier, ie, for the the linked section to exclusively fill the browser window. it could be done with an ugly hack that would make scrolling from section to section excruciating, as some might prefer.

your desired functionality is convenient for users and is currently the use case having multiple documents. the down side to having multiple documents and why I am working on a single document format, is solely to make documentation maintenance easier by those with minimal html and css skills going forward. multiple documents can each have their own way of doing things requiring more maintainer expertise.

[user1234]

Do you know how I can make the scroll back button return to the TOC rather than to the top of the page? If the preface or heading was larger, one would have to scroll down to the TOC after using the button.

Yes! Just a bit of javascript to be used. Take a look at installation.htm, line 8 to line 34. It only is an example of storing last used id, color its background. You can do something same to load the page to previously used id, but does not scrolls it back to the position where the user was at (say if the user scrolled through the page, i.e. he was still at no particular id, then he used reference, then clicked the button to go back to top, then this would not be possible to scroll back to the position the user left at).

[user1234]

@bigpup, @williwaw, as I used jammy64 more and more, I got to know what it does. For example, it uses connman-gtk as network manager. @dimkr allowed us to add apt to jammy64. Now, apt is used as default package manager (PPM though can be used as well to install puppy specific packages). And there's lot more!

I have created documentation for using connman-gtk, but cannot provide it to you today. Will post it tomorrow.

I think a file for usage of package manager would be needed as well. I'll work on it tomorrow.

Jammy64 is currently under development, still I like it, for it being able to install packages using apt. I think, just a bit more of refining and we are done with jammy as well (at least its first released).

[dimkr]

You'll need to find a way not to write documentation that's only true for jammy64. @peebee's builds don't have apt and don't use ConnMan, for example.

[wizard]

@dimkr

You are right, the docs as they are now need to be very generic, but is there a way to add distro specific docs when the distro is built?

Thanks
wizard

[dimkr]

AFAIK there's no such mechanism. But even if we add something like this, the documentation can run out of sync with the build configuration. For example, ScPup's build configuration is not part of woof-CE, so the list of packages and the documentation are not maintained together.

[williwaw]

You'll need to find a way not to write documentation that's only true for jammy64. @peebee's builds don't have apt and don't use ConnMan, for example.

when one builds a puppy from woof-ce, are there defaults when choosing apps for common utilities like package management or connectivity? The sort of apps that a documentation project should prioritize?

My first foray from XP to an open source OS was FreeBSD. After looking at many Linux distros including Puppy 4.2.1 , the choice was made based on the quality of documentation available.
Don't know if many other make choices this way.

[williwaw]

line 8 to line 34

that seems to be the way to go especially with your scroll button :thumbup2: thanks
unfortunately, it broke my single page html when I tried to copy the script to <style>, and the script is a few pay grades above my ability to troubleshoot. I did implement a simple html method which I will see how it works out as the TOC grows.

I have what I think is a workable page template for now, and need to move on to creating a comprehensive TOC ,even if there are not docs currently available for all the items in the TOC to point to. Has anyone seen some nice examples from other projects that could serve as working basis for where puppy documentation needs to be?

[williams2]

Has anyone seen some nice examples from other projects that could serve as working basis for where puppy documentation needs to be?

BSD documentation included with live cds seems like a good example.
though it might not be good for your purposes.

The all-in-one html file is about 3 MB, gzipped it is about 670 K.

https://www.FreeBSD.org/

EDIT: forgot url

[user1234]

You'll need to find a way not to write documentation that's only true for jammy64. @peebee's builds don't have apt and don't use ConnMan, for example.

So, leave documentation for jammy64? The docs must be kept for latest puppy, still having some if and else statements in it. For example, I have included a statement in connman-gtk docs that if connman-gtk is not found, then use some other program. SNS doc is still kept.

I think it might be great to move the docs to a seperate repo and then allow the developers to fork it and modify according to their needs and include it in their puppy. Maybe, add a statement in _00build.conf like DOCS_URL from which docs could be gotten. And if DOCS_URL not found then get the docs from the puppylinux repo. What about the idea?

[dimkr]

I think it would be good enough if you put the ConnMan-related documentation inside the connman-gtk petbuild (woof-code/rootfs-petbuilds/connman-gtk/usr/share/doc) and the SNS documentation in woof-code/rootfs-packages/simple_network_setup/usr/share/doc.

If you use the same file name (say, network-setup.html) in both places, you can put a link in index.html and it work in both cases.

If the documentation is moved to a separate repo it will be easier for it to run out of sync with woof-CE. If I rebuild jammy64 tomorrow using an old version of woof-CE, the documentation repo might include documentation for features only available in a Puppy built using a newer woof-CE.

[user1234]

I think it would be good enough if you put the ConnMan-related documentation inside the connman-gtk petbuild (woof-code/rootfs-petbuilds/connman-gtk/usr/share/doc) and the SNS documentation in woof-code/rootfs-packages/simple_network_setup/usr/share/doc.

If you use the same file name (say, network-setup.html) in both places, you can put a link in index.html and it work in both cases.

If the documentation is moved to a separate repo it will be easier for it to run out of sync with woof-CE. If I rebuild jammy64 tomorrow using an old version of woof-CE, the documentation repo might include documentation for features only available in a Puppy built using a newer woof-CE.

Create branches! The repo may include branches which could be forked from the base branch as a new puppy release is launched. Then make it compulsory to include DOC_URL. Otherwise ask in 3builddistro?

It may become a very tedious task to create documentation in petbuild dir and then copying it to /woof-code/rootfs-skeleton/usr/share/doc on build time.

[user1234]

I have completed with HOWTO_connman-gtk.htm. Here is the file(s) (includes image files as well):-

HOWTO_connman-gtk.tar.bz2

(71.7 KiB) Downloaded 39 times

HOWTO_Internet.htm is also updated to include link to HOWTO_connman-gtk.htm.

@bigpup. @williwaw, @dimkr, please review.

Full doc folder can be found at https://github.com/lakshayrohila/woof-C ... ion-update.

BTW, I have also updated 3builddistro so that it does not remove connman-gtk_imgs and sns_imgs dir on build time. Here is the updated file- https://github.com/puppylinux-woof-CE/w ... 91351c94d2. @dimkr, please review if the updated 3builddistro is OK or not.

[dimkr]

It may become a very tedious task to create documentation in petbuild dir and then copying it to /woof-code/rootfs-skeleton/usr/share/doc on build time.

This copying is not a manual step during the build process. What I mean is, a Puppy built using woof-CE which has the connamn-gtk petbuild includes all files from the connman-gtk directory, and you can put the relevant documentation there to include it in any Puppy that uses this petbuild. And, if you want to add documentation that's true only for every Puppy that uses SNS, you can put that documentation in the SNS directory under rootfs-packages.

[user1234]

It may become a very tedious task to create documentation in petbuild dir and then copying it to /woof-code/rootfs-skeleton/usr/share/doc on build time.

This copying is not a manual step during the build process. What I mean is, a Puppy built using woof-CE which has the connamn-gtk petbuild includes all files from the connman-gtk directory, and you can put the relevant documentation there to include it in any Puppy that uses this petbuild. And, if you want to add documentation that's true only for every Puppy that uses SNS, you can put that documentation in the SNS directory under rootfs-packages.

If you say so, I'll do it. But what I want that the puppy documentation opened by pressing Help button in the Menu should also contain a link to those documentations. How'd you do that?

[dimkr]

Create branches!

Most Puppy developers don't have the required git know-how. Some woof-CE contributors who push changes into woof-CE just edit files through the GitHub UI, and probably don't know how to use git really.

Also, most Puppy releases are built with woof-CE plus local modifications (and that includes Fossapup, ScPup, VoidPup ... you name it), so while it is possible to create a woof-CE branch at the time of release, this branch will usable only for one person, who has the extra files and manual patches applied on top.

[dimkr]

If you say so, I'll do it. But what I want that the puppy documentation opened by pressing Help button in the Menu should also contain a link to those documentations. How'd you do that?

Just put a link to network.html in index.html, and supply network.html in two places: inside the connman-gtk petbuild and under the SNS directory in rootfs-packages. Every Puppy built with woof-CE will include network.html from one of these places.

[user1234]

If you say so, I'll do it. But what I want that the puppy documentation opened by pressing Help button in the Menu should also contain a link to those documentations. How'd you do that?

Just put a link to network.html in index.html, and supply network.html in two places: inside the connman-gtk petbuild and under the SNS directory in rootfs-packages. Every Puppy built with woof-CE will include network.html from one of these places.

Ok, I understand now, and I actually have started to like the idea. I'll update my files as required.

One more problem to solve-
What if a puppy has both connman-gtk and sns? Then, network.htm would be overwritten by the latter one's network.htm (if $PETBUILDS is set in an alphabetical order). Then we'll have to, I think, first check if network.htm is present at usr/share/doc, and if not found then use cat doc > usr/share/doc, otherwise cat doc >> usr/share/doc in pinstall.sh of that petbuild?

[user1234]

And as you're online now, I wanted to discuss the HOWTO_modem.htm (which I renamed to HOWTO_dialup.htm) problem with you. Does woof-CE still support connecting using dialup method? And if yes, then how? I think its documentation would need most changes.

[dimkr]

What if a puppy has both connman-gtk and sns?

Don't worry about that, anyone who does this has zero understanding of what they're doing and will remove one of them. They conflict and you can't use both at the same time.

[user1234]

@dimkr, doing the requested changes. Thanks!

[dimkr]

Thank you @user1234 for helping make Puppy better!

If anyone wants to follow this good example and join the development of woof-CE, please don't hesitate: nothing is set in stone and Puppy has always been a do-ocracy.

[bigpup]

I think a file for usage of package manager would be needed as well. I'll work on it tomorrow.

Keep in mind, that most Puppy programs, have their own help, that is accessed by clicking the help in the actual program, main window.

Puppy Package Manger is this file:
usr/local/petget/help.htm

I wonder if connman-gtk could have a help button in it's main window taking you to HOWTO_connman-gtk.htm

[user1234]

I think a file for usage of package manager would be needed as well. I'll work on it tomorrow.

Keep in mind, that most Puppy programs, have their own help, that is accessed by clicking the help in the actual program, main window.

Puppy Package Manger is this file:
usr/local/petget/help.htm

I wonder if connman-gtk could have a help button in it's main window taking you to HOWTO_connman-gtk.htm

We have developed rather a better way! Both connman-gtk and sns share same how to file name- HOWTO_network_setup.html, and HOWTO_Internet.htm has a link to that file. They both are placed in different dirs and thus will be copied when the developer decides to add sns or connman-gtk to his build. We assume that the person who builds puppy would either use sns or connman-gtk only. There is also an option for frisbee to be installed, I think; so maybe write documentation for that too.

I don't think any other network manager would be installed by a developer. Rather we should also guide him to only install any one of these, only one.

And if HOWTO_network_setup.html still isn't created, then maybe add some thing in pinstall.sh which either reports the developer that HOWTO_network_setup.html was not found, or do something else?

What dou you think, @bigpup and @dimkr?

[williwaw]

I think it might be great to move the docs to a seperate repo and then allow the developers to fork it and modify according to their needs and include it in their puppy. Maybe, add a statement in _00build.conf like DOCS_URL from which docs could be gotten. And if DOCS_URL not found then get the docs from the puppylinux repo. What about the idea?

If the documentation is moved to a separate repo it will be easier for it to run out of sync with woof-CE. If I rebuild jammy64 tomorrow using an old version of woof-CE, the documentation repo might include documentation for features only available in a Puppy built using a newer woof-CE.

@dimkr
Wouldnt user1234 idea be suitable to host documentation that is useful to puppy builders but not applicable to all woof-ce built pups? And also a place for devs to provide links to pages for the users to read? Perhaps a documentation dedicated repo at https://github.com/puppylinux if not woof-ce?

[bigpup]

Any how to do something help file is always good to have.

Keep in mind it is still a file taking up space in the overall Puppy OS, that gets loaded into RAM.
So, the file is using RAM, even when not being looked at.

Still wonder if a how to for using a specific program, is also needed, if the program already has it's own help.

Your idea on where to put the files seems good to me.
Placing a specific program how to in a directory for that program, seems to be what the different directories in /usr/share/doc are about.
Links in one file taking you to another file seems to be one big advantage of having individual files.

I don't think any other network manager would be installed by a developer. Rather we should also guide him to only install any one of these, only one.

For many years this has been the provided programs for network connection.
As stated in this selection window, each one has it's advantages and disadvantages.

Screenshot.png (54.2 KiB) Viewed 1557 times

.
Depending on the hardware, I have found times when the one you select to use will determine if you will actually get a network connection setup working.
.
.

[dimkr]

And if HOWTO_network_setup.html still isn't created, then maybe add some thing in pinstall.sh which either reports the developer that HOWTO_network_setup.html was not found, or do something else?

What dou you think, @bigpup and @dimkr?

I don't think this matter much, building a Puppy with zero or multiple, conflicting network management solutions is just nonsense. Nobody would do that (then release the build output), and I don't see a reason to complicate the code to handle these corner cases.

Depending on the hardware, I have found times when the one you select to use will determine if you will actually get a network connection setup working.

That's because SNS and Frisbee are imperfect and have issues that need to be reported and fixed. I don't like this two half-working tools situation, that's why I don't include them in my builds.

Wouldnt user1234 idea be suitable to host documentation that is useful to puppy builders but not applicable to all woof-ce built pups?

It's OK to provide documentation that works only for jammy64, it's not the end of the world, but doesn't improve documentation for Puppy as a whole.

Consider these consequences:
1. We're a small project. If 80% of the documentation is true for any Puppy built with woof-CE, it's a waste to provide this documentation in a format (for example, a directory of .html files, some jammy64-specific) that prevents some woof-CE users from using it.
2. We're a small project, I think it's a bad idea to divide woof-CE into woof-CE and a separate documentation project. This would add more work, more need for coordination, and raise the entry barrier for new contributors.
3. If the documentation is moved outside of woof-CE, developers will need to fork it to make adjustments and drop jammy64-specific things. These forks will slowly run out of sync with the jammy64 documentation and rot away. It would be healthier for this documentation project if those shared 80% are placed in a shared location (say, woof-CE's rootfs-skeleton/usr/share/doc), but with some mechanism that allows the 20% with distro-specific adjustments to sit somewhere else (IMO, preferably other directories in the woof-CE source tree and not some external project, so everything is maintained together).

IMO the right solution is to do exactly what @user1234 is doing right now: clean up rootfs-skeleton/usr/share/doc by removing irrelevant (like the intro to regular expression) or misleading documentation that doesn't work, modernizing things a bit (i.e. Inkscape vs. Sodipodi), and making some documentation optional (for example, removing pmusic documentation if pmusic is not included in the build, or providing ConnMan-specific documentation instead of SNS-specific documentation in a build with ConnMan).

If the documentation is moved out of woof-CE I think we'll be in the same situation again and again.

[user1234]

And to provide the remaining 20% documentation specific to a build, I am trying to do exactly that in https://github.com/puppylinux-woof-CE/woof-CE/pull/3655. Once it is complete and the reviewers accept it, it may be merged into woof-CE .

(And you may also be able to see there the amount of buggy codes I write . @dimkr is currently helping me fix all the bugs. Thank you @dimkr!)