Add Dependency Guide to docs

[naeluh]

Hi @geealbers hope you had a great weekend! Here is top level dependency guide that explains which package/libraries are at the core of quire-cli and quire-starter-theme. I think this works as a starting point but can updated and improved as these change or get updated.

Let me know if you have any questions or if I can clarify in any way.

Thanks!

[geealbers]

@naeluh this is great. I made a few proofreading changes for typos and to match style in the rest of the guide. I'd also like to get this a bit more specific if possible. In your first paragraph you write:

This page explains what makes these two projects work and what major dependencies currently make quire what it is.

I think you're doing a great job with the second part of this in describing the major dependencies that make Quire what it is. Now, I'd like to add in more specific info about the first part, "what makes these two projects work". I had in mind just a simple table of all the dependencies listed in package.json in each of the two projects, with the basic NMP description, and then a sentence or two on what purpose exactly each is serving for Quire. I pushed an initial version of the tables for the CLI in a new commit to this PR. If this approach makes sense, I could add in similar tables for the starter theme dependencies, and I'd just need you to go in an fill in the info in that last column "Function in Quire". What do you think?

[naeluh]

Hi @geealbers thanks! Hope you had a great 4th!

When I started writing the page, the audience I was thinking about was quire users that were strictly trying to process there docs into the outputs that quire offers. I feel as though information on all dependencies might not be useful to that audience? I thought if I gave a top level view of the software that actually executes the file conversions and the tools that would be used to edit the design would suffice.

I also thought about what if the person who reads this is a coder and wants to develop features for quire, what would they want to see. I feel as though they would see this information in the package.json and would have to do a deeper dive into the supporting dependencies to understand what actually is going on in the code or they already know what they are would not need it explained in the docs.

In terms of what supporting dependencies do for quire. For example lets take axios, in the table you wrote "Promise based HTTP client for the browser and node.js" for the NPM Description, the weird part of this is that is exactly what axios does for quire, because that is axios' function and that is what it is used in any context or in any project. In my opinion this goes for all the dependencies, they can only really be used in one way and that is how quire uses the and outside of writing about the one function it is used in I am not sure what other information would be helpful. Continuing with the axios example, it is used in epub.js on line 89 axios executes a http promise request to get the chapters and is never used for anything else. There are many libraries out there that do this kind of thing, axios just happens to be one of the more popular and easier to use ones and truly that is the reason for its implementation in the code.

So basically my point is adding a section called "Function in Quire" for each one might not really help in understanding anything about Quire (quire-cli or quire-starter-theme) because these packages have one use and that why it is being implemented in the project. However listing them in the table with the description and then maybe adding a link npm page or github would be helpful.

Let me know what you think about that or who do you think the intended audience is and what information they would be after.

Also let me know if you have any questions or if I can clarify in any way.

Thanks!

Nick

[geealbers]

Thanks for updating the dependency tables @naeluh, and I'm excited to have Quire working on PCs! Will you also need to make any updates to the quire-cli or quire-starter-theme repos for PC support?

@mbelhu, can you take a pass to tidy up and clarify Nick's new PC install instructions before we merge this PR? To do so, I think you'll need to actually test them out on a PC just as we did for Macs. You should be able to use our old PC laptop for the non-Widows 10 directions. For Windows 10 though, we'll need to get our hands on a newer machine. I'll email you details about that. And as you are working on it and doing testing, reach out to Nick if you run into any issues or need clarification on anything he's got there. Thanks!

[geealbers]

Also, we may have to be a little more explicit with this in the final version of the docs, but I love the line "choose your favorite Linux distribution". I really keep laughing to myself about it. Makes me feel like such a failed nerd for not already having a favorite! 🤓

[naeluh]

Hi @geealbers ! Hope you are having a great day! Those install directions are not done yet. But yes that would be great to get some help with the writing, thanks! Haha yeah there are 2 ways to install the Windows Subsystem for Linux one let you choose the distribution and one is only Ubuntu (my favorite haha) maybe that would be easier?

Yes there are a few edits in quire-cli also I needed to update pe-pub again. For the time being I moved pe-pub and pe-pub-fs into quire-cli instead installing from the repository. If the code works I will put in another pull request with the maintainer to update the repository or we could just keep it in quire since the code is not getting maintained int that repository? I'm cool with either way. Let me know if you have any questions or if I can clarify in any way.

@mbelhu when the instructions are ready you can access the code using the pc-dev branch here -> https://github.com/gettypubs/quire-cli/tree/pc-dev

@mbelhu let me know if you have any questions I am happy to help!

[naeluh]

Hi @geealbers @mbelhu

The instructions are ready to go

https://github.com/naeluh/quire/blob/naeluh-doc/content/resources/install-pc.md

Let me know if you have any questions

Have a great weekend!

thanks!

[mbelhu]

@naeluh thanks for writing the instructions! I've started to review them and got some (silly) questions for you:

• Instructions for Windows 10 install of node.js and npm through nvm:

There're a couple notes mentioning OS X and Windows users might not need them:

Note: Since OS X 10.9, /usr/bin/git has been preset by Xcode command line tools, which means we can't properly detect if Git is installed or not. You need to manually install the Xcode command line tools before running the install script, otherwise, it'll fail. (see #1782)

Note: On OS X, if you get nvm: command not found after running the install script, one of the following might be the reason:-
- your system may not have a [.bash_profile file] where the command is set up. Simply create one with touch ~/.bash_profile and run the install script again
- you might need to restart your terminal instance. Try opening a new tab/window in your terminal and retry.

Do you think is fine to remove them?

• Other Windows users:

• Git-BASH install: On the setup wizard screens I get several options every time I click "next" (like "how would you like to use Git from the command line?"). Are default options OK or do we tell users to chose something else?

• Is LTS the Node.js version users have to download?

• To run Powershell as administrator I followed the instructions from this site https://www.digitalcitizen.life/how-run-programs-administrator-windows-7 Are they good or do you know a better way?

This is all I got so far. I may have more questions once I've access to a Windows 10 computer.

Thanks!

[naeluh]

Hi @mbelhu hope you are having a great day!

For Win 10 users:

Yes you are correct it should not include that mac info.

I actually just took the install instructions verbatim in the interest of time.

I will remove the unneeded points and let you know when it has been updated.

For All other Win users:

Git-BASH install: On the setup wizard screens I get several options every time I click "next" (like "how would you like to use Git from the command line?"). Are default options OK or do we tell users to chose something else?

Yes use the default options, that will work fine.

Is LTS the Node.js version users have to download?

We could go either way on this it will work both ways. So for the time being yes the latest LTS version is what users should download.

To run Powershell as administrator I followed the instructions from this site https://www.digitalcitizen.life/how-run-programs-administrator-windows-7 Are they good or do you know a better way?

For this you should be able to right click on the icon and select "run as administrator" from the context menu, that appears to be what that link is asking you to do. So yes you are correct.

Let me know if you have any other questions or if I can help in any way.

Thanks!

[naeluh]

@mbelhu I just made some updates to the install-pc, let me know if that works.

Thanks!

Nick

[mbelhu]

Great! Thanks @naeluh

[naeluh]

Hi @mbelhu @geealbers

I am going to rewrite the win 10 users to have a link and once a user has full filled the requirement of adding linux to there win 10 install then they can head over to linux install instructions and go from there, since they will effectively be the same. I will let you know when that is in place.

thanks!

Nick