build instructions dedicated page?

goyalyashpal commented 2 years ago

I think the main site should have a page dedicated to the setting up via source.
currently the instructions are at 2 separate places - the readme, and the pdf
both these requires additional manual filtering to reach the particular section (scrolling the pdf pages, or hunting the readme document)
since am new to building software from src and that too dealing with one which other people have trouble accomplishing, admittedly being a bit picky here - this added hurdle deters the main task more
so, having a separate dedicated page would help open the link directly and focus on that content solely
that page - obviously can be typeset - which can inturn feed back to the pdf as well - if that's wanted or such

goyalyashpal commented 2 years ago

also, https://github.com/sile-typesetter/sile/blob/2afb5fa9500daef01f2e4d6229eb04d47f91a2ca/README.md?plain=1#L266-L267

Omikhleia commented 2 years ago

(Out of curiosity, why do you need to build SILE from source rather than use a standard distribution, and on which system? And what is the problem with the quoted bit of README? -- Maybe the second line, mentioning examples, these were moved indeed to the website (i.e. to https://github.com/sile-typesetter/sile-typesetter.github.io - That needs to be updated probably)

goyalyashpal commented 2 years ago

on which system

windows

these were moved indeed to the website (i.e. to https://github.com/sile-typesetter/sile-typesetter.github.io - That needs to be updated probably

yes, am working on it

update: pull 1561

dontlaugh commented 2 years ago

why do you need to build SILE from source

SILE is under active development, and I've wanted to build from source to just ensure that my environment is consistent across more than one computer.

Omikhleia commented 2 years ago

Heya @dontlaugh - On Linux, I am achieving that exact aim with a customized docker image (so it also has my fonts, some of my packages pre-installed, etc.), so that I don't have to add all dependencies creeping up on more that one computer (beyond docker, obviously). FWIW, I plan to document it at some point (i.e. when I am satisfied with it). Not that there is much to say really (it's just a derivation of SILE's Dockerfile, with customizations applied)

goyalyashpal commented 2 years ago

hi,

will it hurt if i move the "### Use as a CI job" section above the "From source" section?
as i don't understand where does CI fit on the spectrum. like do this run on offline local machine too? i have only seen CI as smth provided by source code hosting services
like is it significant that it comes after "from source" ... "testing" part, or is the placement there an arbitrary one and hence it can be moved around?

alerque commented 2 years ago

The reason CI is listed after the "from source" heading is that I was listing all the ways to get and install on local platforms together, and "from source" is a last resort option in that vein. CI is kind of a different sort of thing. It should probably actually be a higher level heading.

CI (Continuous Integration) systems come in many flavors but are not typically remote, not local. The CI section is dedicated to the ways SILE can be run from CI systems. There are offline local variants of these systems, but it would not be relevant to explain in the README. People using one will know about how the rules apply to them.

If you want roughly the equivalent of the CI but for local machines, you should be just looking at the container options such as Docker which can be run locally. Many CI integrations are just small wrappers around the Docker container to integrate them with the CI system's options.

alerque commented 2 years ago

Re a dedicated page...

I'm unsure about the wisdom of adding a 3rd place to document this. If anything I would suggest putting a stub on the website linking back to the readme, or perhaps we could setup something to just mirror the relevant bit of the readme to there. It's important that it stays up to date though, so it would have to be automated. We already fall behind updating the instructions in the manual that are largely duplicated from the README.

Dropping the instructions from the README is not an option. They must be here because the project source gets copied around and automatically scrapped and shows up in documentation of the project in many places we do not control. Installation instructions are a standard expectation for open source README pages. Anywhere else we choose to post them is going to be in addition to that.

About your case specifically, we just don't have good instructions for Windows because nobody is officially maintaining it there. We'd love to see that situation improve, but moving the docs to a different site wouldn't make it any easier for Windows folks since we don't have anything better to say.

Omikhleia commented 2 years ago

Re CI: One can also run Github CI actions locally with solutions such as act - I have been using that when I was working on lunamark, to pass the tests without having to install anything else (i.e. as if I had been pushing my code to trigger the CI pipelines). (I've not tried for SILE itself).

goyalyashpal commented 2 years ago

It should probably actually be a higher level heading.

i was thinking same, so, should i do it?

or perhaps we could setup something to just mirror the relevant bit of the readme to there

i was thinking same on this too, but don't know how that's done in the repos - like i see that shortcut symbol on some directories in many repos here on github

Dropping the instructions from the README is not an option

not even having a separate file in the same repo? I have seen stuff like DOCUMENTATION.md or BUILDING.md in some repos. Won't that kind of thing be useable here?

alerque commented 2 years ago

It should probably actually be a higher level heading.

i was thinking same, so, should i do it?

Sure, make it part of your other PR.

or perhaps we could setup something to just mirror the relevant bit of the readme to there

i was thinking same on this too, but don't know how that's done in the repos - like i see that shortcut symbol on some directories in many repos here on github

It's not that easy. They are different repos and it would require special build rules and post processing. I know how it would be done but do not plan on doing it just yet. For now focus on making the install instructions in the readme as good as possible.

Dropping the instructions from the README is not an option

not even having a separate file in the same repo? I have seen stuff like DOCUMENTATION.md or BUILDING.md in some repos. Won't that kind of thing be useable here?

No, that would loose some exposure. Not all places that scrape projects dive deeper than the readme. When more distros are on broad we can shift the focus of the readme to be an overview of many different topics, but for now it's 95% dedicated to how to get up an running in any circumstance. I want it to stay that way for now.

goyalyashpal commented 2 years ago

When more distros are on broad we can shift the focus of the readme to be an overview of many different topics, but for now it's 95% dedicated to how to get up an running in any circumstance. I want it to stay that way for now.

fair enough, makes total sense. So, closing as not planned for now.

P.S. i am impressed by how well u understand what i wanted to say and also put ur own input so precisely as well. it feels nice. thanks 👍

sile-typesetter / sile

build instructions dedicated page? #1560