Re: [WIP] New package: void-docs-2020.04.18.

Re: [WIP] New package: void-docs-2020.04.18.

[Chocimier]

[-- Attachment #1: Type: text/plain, Size: 272 bytes --]

New comment by Chocimier on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621376154

Comment:
Good idea.

Since we avoid to package anything without tag, we should rather set a good example and use tags for own stuff too.

Re: [WIP] New package: void-docs-2020.04.18.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 1179 bytes --]

New comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-623031734

Comment:
Anyone here with good findutils skills? I used `fd` instead because running commands with it is way easier.

So, right now, we have:

* markdown sources -> straight from the git repo
* HTML book -> generated by mdbook, can be opened by a TUI or GUI browser. I'd expect someone who is doing a graphical install to have an internet connection, so this probably isn't as useful, but it's easy enough to include
* mandoc pages -> generated with pandoc (wonderful tool, btw). We could customize page titles a bit more too, to get more unique ones. Requires `mandoc -a file` to browse files with a pager, and obviously can't link directly to  another file. I used `file.7`, because 7 is the misc category. If you have better suggestions please let me know. @travankor it's the closest I could get to texinfo :p

The PR is still WIP, so when we decide on a tagging strategy I will update it to use that instead.

@bobertlo regarding tagging, I'd like to wait for a few PRs too. Stuff like chroot guides would be pretty useful, I think.

Re: [WIP] New package: void-docs-2020.04.18.

[bobertlo]

[-- Attachment #1: Type: text/plain, Size: 412 bytes --]

New comment by bobertlo on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-623016118

Comment:
I think there should be tags for sure. At least as far as staying consistent. We wont ever pull from master. The package should be fairly small so I think some regular interval when there are small changes and then manual updates for larger changes would be appropriate.

Re: [WIP] New package: void-docs-2020.04.18.

[bobertlo]

[-- Attachment #1: Type: text/plain, Size: 343 bytes --]

New comment by bobertlo on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-623015408

Comment:
@ericonr there is a lot of pending content. i think merging some of this might be appropriate before tagging. on the other hand tagging now before we start getting the changes in might make sense also.

Re: [WIP] New package: void-docs-2020.04.18.

[CameronNemo]

[-- Attachment #1: Type: text/plain, Size: 580 bytes --]

New comment by CameronNemo on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-622605404

Comment:
Well the void-docs are pushed to the website directly from master, so theoretically it should not be in the middle of updates. One option could be timing the doc tags with live image builds.

As far the file format discussion, I would prefer shipping both the markdown and compiled mdbook. This would allow for a simple and quick `less path/to/doc` as well as the option of using a text or non-text browser to navigate the full book.

Re: [WIP] New package: void-docs-2020.04.18.

[Chocimier]

[-- Attachment #1: Type: text/plain, Size: 421 bytes --]

New comment by Chocimier on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-622481270

Comment:
Tag means that tagged version is in reviewed, usable state, not eg. in middle of some series of patches, and that there are enough changes from previous tag to update.

I guess it's easier to take existing package into image, than build it from master during image generation.

Re: [WIP] New package: void-docs-2020.04.18.

[travankor]

[-- Attachment #1: Type: text/plain, Size: 363 bytes --]

New comment by travankor on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-622209050

Comment:
Can the live cds just use master of void-docs, like they do with void-packages (i.e. use the lastest version of everything when generated)? I don't know what @bobertlo says, but release tagging might be too bureaucratic.

Re: [WIP] New package: void-docs-2020.04.18.

[travankor]

[-- Attachment #1: Type: text/plain, Size: 364 bytes --]

New comment by travankor on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-622209050

Comment:
Can the live cd's just use master of void-docs, like they do with void-packages (i.e. use the lastest version of everything when generated)? I don't know what @bobertlo says, but release tagging might be too bureaucratic.

Re: [WIP] New package: void-docs-2020.04.18.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 576 bytes --]

New comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621893470

Comment:
@travankor the idea is to ship something with the livecd, primarily. That's why we'd need to tag a version. I agree that documentation is rolling in nature, but we can try to make a target for a tagged version by closing some important issues.

mandoc seems like an interesting option, however. I used pandoc to convert the files into roff, and `mandoc -a SUMMARY` actually looks really good. And it should come with the base system!

Re: [WIP] New package: void-docs-2020.04.18.

[travankor]

[-- Attachment #1: Type: text/plain, Size: 424 bytes --]

New comment by travankor on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621776418

Comment:
What do tags mean for documentation? Is there a 1.0? Documentation is updated on a "rolling"-release basis. Should people just git clone like with xbps-src, which will give you the latest info?

Also not a fan of shipping a md reader as part of the base system. How about mandoc?

Re: [WIP] New package: void-docs-2020.04.18.

[travankor]

[-- Attachment #1: Type: text/plain, Size: 332 bytes --]

New comment by travankor on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621776418

Comment:
What do tags mean for documentation? Is there a 1.0? Should people just git clone like with xbps-src?

Also not a fan of shipping a md reader as part of the base system. How about mandoc?

Re: [WIP] New package: void-docs-2020.04.18.

[travankor]

[-- Attachment #1: Type: text/plain, Size: 332 bytes --]

New comment by travankor on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621776418

Comment:
What do tags mean for documentation? Is there a 1.0? Should people just git clone like with xbps-src?

Also not a fun of shipping a md reader as part of the base system. How about mandoc?

Re: [WIP] New package: void-docs-2020.04.18.

[ericonr]

[-- Attachment #1: Type: text/plain, Size: 244 bytes --]

New comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/21453#issuecomment-621491731

Comment:
@Chocimier good point! I will talk to @bobertlo about this to see when he thinks we could tag the docs.