src/xbps/index.md: Link to void-packages/Manual.md #639
Conversation
| @@ -30,10 +30,14 @@ Most general package management is done with the following commands: | |||
| Most questions can be answered by consulting the man pages for these tools, | |||
| together with the [xbps.d(5)](https://man.voidlinux.org/xbps.d.5) man page. | |||
|
|
|||
| To learn how to build packages from source, refer to [the README for the | |||
| To learn how to build packages from source, refer to [the README of the | |||
There was a problem hiding this comment.
This seems like a pedantic change.
There was a problem hiding this comment.
This should be:
- Unchanged, which is idiomatic;
- "the README in the void-packages repository", if there is some compelling reason that "for" is inappropriate; or
- Something simpler like "the void-packages README".
The word "of" conveys a possessive quality that the repository itself cannot manifest. It is not correct here.
src/xbps/index.md
Outdated
| void-packages | ||
| repository](https://github.com/void-linux/void-packages/blob/master/README.md). | ||
|
|
||
| To learn how to create new packages, refer to [the Manual of the |
There was a problem hiding this comment.
This doesn't really explain how the README and the manual differ.
There was a problem hiding this comment.
I disagree. Building packages and creating packages seems quite different to me.
There was a problem hiding this comment.
What do you think about: "To learn how to create new packages templates [...]"?
There was a problem hiding this comment.
I changed it to "package templates" now, also ran vmdfmt on it. It should pass the test now...
Add link to instructions for creating new packages.
|
I now ran |
| To learn how to create new package templates, refer to [the Manual of the | ||
| void-packages | ||
| repository](https://github.com/void-linux/void-packages/blob/master/Manual.md). |
There was a problem hiding this comment.
Can we phrase this in a different way from the previous paragraph? Just copying it and changing a few words doesn't make it readable. It could be something like "..., Manual.md in the same repository describes how to create, update or modify packages."
There was a problem hiding this comment.
Generally, of course yes. But I actually find it pretty readable this way. I did not just copy it because I'm lazy, I just wanted to keep it as simple as possible. IMO, the repetition kind of emphasizes the difference between building packages and creating package templates. Your version right now says "create, update or modify packages", but "create packages" could be misunderstood for "building packages" by beginners, as @abenson mentioned. I would stick with "package templates" in the second sentence. I would also omit the "update" in your version, since that could still be misunderstood for updating the packages on the system, and also it's included in "modifying packages" IMO.
There was a problem hiding this comment.
Maybe a broader rewrite will better clarify the distinction:
The [README] provides a general overview of xbps-src and instructions for building packages locally from existing templates. For information about adding new templates or altering existing templates, refer to the [Manual].
The README has this as its third paragraph, does it even make sense to mention here? |
| @@ -30,10 +30,14 @@ Most general package management is done with the following commands: | |||
| Most questions can be answered by consulting the man pages for these tools, | |||
| together with the [xbps.d(5)](https://man.voidlinux.org/xbps.d.5) man page. | |||
|
|
|||
| To learn how to build packages from source, refer to [the README for the | |||
| To learn how to build packages from source, refer to [the README of the | |||
There was a problem hiding this comment.
This should be:
- Unchanged, which is idiomatic;
- "the README in the void-packages repository", if there is some compelling reason that "for" is inappropriate; or
- Something simpler like "the void-packages README".
The word "of" conveys a possessive quality that the repository itself cannot manifest. It is not correct here.
| To learn how to create new package templates, refer to [the Manual of the | ||
| void-packages | ||
| repository](https://github.com/void-linux/void-packages/blob/master/Manual.md). |
There was a problem hiding this comment.
Maybe a broader rewrite will better clarify the distinction:
The [README] provides a general overview of xbps-src and instructions for building packages locally from existing templates. For information about adding new templates or altering existing templates, refer to the [Manual].
|
@ericonr IMO it would still be helpful to have a reference about creating templates from here, since this is probably the place where users start looking/searching. If we don't link to the Manual from here, then I would at least mention that information about creating templates can be (indirectly) found in the Readme (even if it's just another link there). But somewhere there should be a reference here about how to create templates IMO. |
Add link to instructions for creating new packages.