Getting started documentation

[Sean Fitzpatrick]

I'm wondering if we're open to some changes/additions to the "getting started" documentation. This is based on a recent email conversation with Greg Hartman, who had been putting off building APEX because he found the existing documentation difficult. 

Some students who were working for me last fall had the same experience. 

Since I knew he (a) runs Windows, and (b) has some version of LaTeX already installed, I sent him the following steps for running PreTeXt locally: 

1. Install Python (from their website, not Anaconda or whatever) 

2. pip install pretext 

3. Clone the book repository

4. Run 'pretext build latex' (since that's the target he wanted to build) 

This had him building the book in only a few minutes. 

Also, if I recall correctly, there's a limit on how long you can have a code space running on GitHub unless you pay, and I'm pretty sure the build time for APEX PDF exceeds that limit. 

With the move to pymupdf for SVG generation, I think 90% of projects will build locally with LaTeX and Python as the only dependencies. (If you need SagePlot life gets significantly harder, I guess.)

[Oscar Levin]

I would say that there can definitely be improvements to the guide.  I don't know whether the official advice should be to do a local install though.  Either way, the guide does have instructions for both codespace and local setups.  

For existing projects, your instructions would be perfect for the project's readme.  Especially for something that takes a long time to build.

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/3d1beeca-b47b-4cdb-8638-3d9f4e83156bn%40googlegroups.com.

[Sean Fitzpatrick]

True. I need to update our README. A lot has changed in the last year or two! 

When I have time I'll read through the existing documentation to see if I can figure out where/why people are getting lost. 

Maybe a short overview/intro would help? 

- About GitHub: you probably want to host your book contents there, and it provides a cloud interface for PreTeXt. See [xref] for details

- About Codespaces: automatic installation of everything you need in the cloud. A few pros and cons... See [xref] for details

- Local installation: steps, pros and cons. Maybe a list of things that are annoying to set up locally. (E.g. if you want SagePlot on Windows)

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/CAOU9BaWgJ07W%2BUVcW3A3kTu7F%3DGHf_PFe4kZ3m2kWx4e200-Xg%40mail.gmail.com.

[Rob Beezer]

There is a pending PR for PyMuPDF which is being actively reviewed. It'd be good not to send anybody down the pdf2svg road for just a few days.

>>> <https://groups.google.com/d/msgid/pretext-dev/3d1beeca-b47b-4cdb-8638-3d9f4e83156bn%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .

>>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "PreTeXt development" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to pretext-dev...@googlegroups.com.
>> To view this discussion on the web visit

>> https://groups.google.com/d/msgid/pretext-dev/CAOU9BaWgJ07W%2BUVcW3A3kTu7F%3DGHf_PFe4kZ3m2kWx4e200-Xg%40mail.gmail.com
>> <https://groups.google.com/d/msgid/pretext-dev/CAOU9BaWgJ07W%2BUVcW3A3kTu7F%3DGHf_PFe4kZ3m2kWx4e200-Xg%40mail.gmail.com?utm_medium=email&utm_source=footer>
>> .
>>
>

[Sean Fitzpatrick]

Yes, that's one of the things I was thinking of. It's mildly annoying to install on Windows. 

Sage might be annoying on most platforms. Ubuntu won't package it any more, except maybe for LTS releases. 

They've stopped Windows support, except via WSL. But my guess is that most projects don't need it.

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAxNi5iZWV6ZXI.1719879651%40quikprotect.

[Steven Clontz]

  >  who had been putting off building APEX because he found the existing documentation difficult. 

IMO it's the responsibility of the APEX project to document how to get started as a contributor to your specific book. It's more important that "Getting Started" instructions be appropriate for someone starting from scratch, and I think the highest impact play for most novices is something that takes minimal clicks and works in a web browser whether you're using Windows, Linux, your cell phone, or a toaster.

You might consider maintaining a wiki as we do for the TBIL project to help with onboarding new contributors: https://github.com/TeamBasedInquiryLearning/wiki/wiki/

[Sean Fitzpatrick]

Right, but what I'm saying is that the impediment here was not a particular project, but not being able to follow the instructions in the Guide to get up and running on Codespaces.

I think someone who has experience with some pretty sophisticated LaTeX work should be able to follow our instructions with no difficulty.

The cloud is fine, but not for everyone. And if you already have Python installed a local install is arguably zero clicks (but 20 keystrokes) ;-)

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-dev/71a2c98c-c47b-4c3b-aea9-9ffb156e21e1n%40googlegroups.com.