Fix sidebox list page

[scottcwilson]

@wiztechinc DrByte pointed out that there was a simple table implementation in this Markdown flavor. You can see it on

https://docs.zen-cart.com/user/new_user_topics/title_change_for_page_x/

(the mapping of the PAGE_ constants to the URL).

I updated content/user/sideboxes/sidebox_list.md to show how to do this for the Information and More Information sideboxes in #395.

In #396 I added per page stylesheets so you don't have to use SASS, you can just style in CSS for the page you are targeting. The stylesheet for this page is content/css/sidebox_list.css.

You can see the result here: https://docs.zen-cart.com/user/sideboxes/sidebox_list/

Does this make sense as a pattern for the remaining sideboxes?

[wiztechinc]

Actually that's what I started out trying to do. It's a much easier way of displaying this kind of info. What and I missed an image? okay, good job, Delia! The only problem is the table doesn't shrink for mobile. I think it needs a max width or cell floats. I shall play.

[wiztechinc]

So the issue is not the tables but the actual path - with no spaces, it commands the full length. Breaking it up with spaces works though looks a bit odd (to us who know). But I think this is best for displaying this page - and I can preview it!!!

[scottcwilson]

with no spaces, it commands the full length

I did have to tweak the SASS. See the change to assets/scss/_variables_project.scss in #395.

[wiztechinc]

[wiztechinc]

If I just reduce the browser on the desktop, it's okay.

[scottcwilson]

Just go ahead and work on this and let me know either when you're done or completely stuck. I have a bunch of my own work to do.

[wiztechinc]

No sweat. I'll get the page formatted with info and we can go from there.

[scottcwilson]

Thanks for your help. If this becomes too much I can take it back and give you something else, but I think you can handle it from here.

[wiztechinc]

Yup, I'm on a roll now!

[wiztechinc]

More unintended consequences. The images reduce in size to a point where you can't see them at all.

I have the entire file ready to go now but I'm not thinking this is going to work. I definitely could not get some rows to work for a third row that starts with an image. Dunno what that's about. I figure I'm missing something important here but maybe not.

Shall I go ahead and do a commit as a different file so you can see it?

[scottcwilson]

I assume you're using Markdown style tables right? If so, revert to using the original style I showed you with the More Information Sidebox for a couple of rows. For the column with the image in it, remove the "width: 25%"- and see if you can make it work for desktop and mobile.

[wiztechinc]

I cannot view mixed markdown / html. I think this is part of the Hugo problem. No Sass either. I created a testing file - I need to do a full PR to view on github at all?

[scottcwilson]

Yes do a PR please.

[wiztechinc]

okay

[scottcwilson]

OK let's do this. I just merged PR #402. This has Information and More Information laid out in HTML with no inline styling. Works on both desktop and mobile. Update your branch so you see this. (It will overwrite your copy of sidebox_list.md so stash that.) If you can see how this looks in your Hugo instance, just copy these blocks for the other images and fill in the notes.

[wiztechinc]

nope, still can't see any of the html. It's the Hugo installation I'm sure at this point. I'll return to it all tomorrow.

[scottcwilson]

I did the first third or so. If you can get Hugo working you can do the rest, or I can take care of it.

[wiztechinc]

Found the solution for the html! And most is displaying correctly. Google is my friend. Your new code definitely is better!

I have to take time to figure out my processes and folders on my computer (and github desktop) but I'm close to being completely functional here. I would expect you don't use the desktop version? Am curious as to how others set up this kind of work.

[drbyte]

Github Desktop is better today than it was a few years ago. They overhauled it and it's more useful now. But I personally find its workflow a bit confusing ... probably because my head is totally comfortable with Sourcetree. They're not vastly different, but I chose not to document Desktop's use because it was so bad when I first wrote up the workflow below.

That workflow is documented here: https://docs.zen-cart.com/dev/contributing/github_workflow/

[wiztechinc]

Thanks, I'm checking out SourceTree now. This is driving me batty. I hate not being productive, but I'm getting there.

[wiztechinc]

ah, one more question which is my biggest issue at this moment. How do I keep the my forked repository up to date on regular basis? Trying to keep the correct stuff up to date seems to be more complicated than it should be? I did a pull request a little while ago but is that the preferred method? Since I can't approve the request, it can't happen on a timely basis while I'm working - understandably - but is there any other way to do this?

[scottcwilson]

How do I keep the my forked repository up to date on regular basis?

Look at the workflow doc Chris provided above.
You will want to do a new PR after updating your fork and merging your changes in.
You want to make your changes on top of what everyone else has done so you don't wipe out any work.

Updating your fork of the doc repo from the command line can be done as follows:

git fetch upstream git checkout master git merge upstream/master git push

[scottcwilson]

At this point I would highly encouarge you to update your repo and create a new PR so we can see the work in progress. I want to be sure you're on the right track.

[wiztechinc]

What I haven't done is any work today since I don't have an updated fork. Thus the questions.

I have gotten used to github and feel more comfortable so I'm not working from the command line. Looking at source tree (I see this is what I checked out long ago maybe because Chris recommended it), it's very different.

I totally understand that I need to keep my fork updated to make sure I don't overwrite anyone else's work. I was just asking about HOW to keep it updated easily. If that needs to happen from the command line - I enter completely new territory.

I do not expect full guidance from y'all. I know how much I have to learn but this is incredibly frustrating since I'm not used to working in unfamiliar territory that has such massive impacts and is visible.

Lunch is best.

[scottcwilson]

You have to pick a tool (Github desktop, SourceTree, command line, whatever) and find a process that works for you.
If you have chosen SourceTree then check their help on how to update your fork.

If you look at mine: https://github.com/scottcwilson/zencart_documentation

you see at the top it says "This branch is even with zencart:master."

Get yours to that point.

https://github.com/wiztechinc/documentation

says This branch is 630 commits behind zencart:master.

[drbyte]

Between PRs I "pull" from github zencart/documentation:master to my local master branch (first I "change to" or "checkout" my local "master" branch, then Pull from master on github). That updates my local with the latest from github.

Then I can optionally update my drbyte/zencart-documentation:master by pushing my local master to github. (But updating my "master" branch on github is moot because I always do pull requests from a named branch, never the master)

If I'm in the middle of a PR in another branch, if none of the files I'm working on relate to any files that have been changed in other PRs that have been merged, I don't need to do anything to update my branch. If nobody else has changed the files I'm PR'ing then there will be no merge conflicts, so I can just do my PR.

However, if someone merges an update to a file I've been working on, I may need to pull the latest master down "into" my current working branch, to get all the updates. Then I can resolve any conflicts (ie: changes that conflict with my changes), before pushing my PR.

This is largely in that github workflow document, albeit maybe explained differently.

None of this requires command-line. It's agnostic of the tool you use to interact with git/github.

[scottcwilson]

I do not expect full guidance from y'all. I know how much I have to learn but this is incredibly frustrating since I'm not used to working in unfamiliar territory that has such massive impacts and is visible.

Rome wasn't built in a day. No one was born knowing how to do this, you have to learn, and it takes time. You think all the other people who have contributed to the documentation did it perfectly the first time? Trust me, they didn't.

BTW, no one made more mistakes starting out with Git than I did. I continually screwed up not branching off master, which meant my PRs had undesired files in them.

[wiztechinc]

Thank you, Scott, for bringing me back to earth. I’m simply not used to flailing! I want to do it perfectly, right out of the gate! (cause, public...)

Chris, I’ll look closer at what you wrote. Part of my issues is that I’m unsure about terminology. Think I’ll do a quick primer on git to cement some things into my brain first.

Then I’ll get that first File up to snuff. Completion, success....., coming.

[wiztechinc]

Hugo is not recognizing the new css file. So the floats aren't working. I don't have to have this working to finish this file but I prefer to view it properly for checks. I had added more info in to the original stuff but I'm not sure based on what you've done that the extra info is welcome. I think it best to do the PR with this and can return for more editing later. But not sure if you ever even saw what I wrote before as it may not have made it to you in the array of different files. My idea is to provide some real details about admin settings as not just info but also as a way to alert the site owner to the fact that there are multiple settings that affect the boxes. I get deep into details. Yea or nay?

[wiztechinc]

oh, and I finally did figure out how to update my fork with github desktop! Thanks for pushing that PR through too.

[scottcwilson]

I think it best to do the PR with this and can return for more editing later.

Yes. Stop with something simple with a line or two about each sidebox. There are other pages that discuss configuration, etc. Model your work on what's already there in this page.

Please do your PR as soon as you can so we can see where you are.

[drbyte]

My idea is to provide some real details about admin settings as not just info but also as a way to alert the site owner to the fact that there are multiple settings that affect the boxes. I get deep into details. Yea or nay?

Perhaps that can be a completely separate PR?

Best to keep PRs topical. Canonical. That way the scope is clearly defined, both for the work being done and also for the reviewer. This also helps prevent frustration if an idea being introduced is rejected, because you're not having to sort out what's being kept vs removed-by-request, etc.

I realize this is very difficult when "creativity is flowing", because "lots of ideas" come to the fore. Keep good notes separately (even open an Issue ticket with the ideas articulated), so they can be revisited.

Keeping things scoped to a narrow focus allows things to be completed and celebrated ... meaning one feels productive and satisfied ..... rather than dragging out for too long and resulting in frustration.

[wiztechinc]

I completely understand what you both are saying. My work process is always multi-layered. Concentrate on code, concentrate on text, then layout and formatting. I do have to proof separately on each level but is my work flow. No frustration in this at all for me. I am writer so prefer to complete the writing while I'm in it. Also I know the frustration of hitting a tiny piece of info or a graphic that teases instead of elucidates. I'm leaning towards links instead of spelling out the admin settings. But refraining for the moment. PR coming shortly.

[scottcwilson]

Remember the point of this page is to simply show a new user the options they have - not to bury them in detail.

Also, as Chris points out, it's best to keep PRs to a single concern. Smaller is easier to merge and complete.

[scottcwilson]

Fixed in #412.