Bug 263955 - handbook/ports: serving poudriere packages privately
Summary: handbook/ports: serving poudriere packages privately
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2022-05-13 18:07 UTC by Jonathan Vasquez
Modified: 2022-05-21 23:33 UTC (History)
2 users (show)

See Also:


Attachments
[patch] serving poudriere packages privately (1006 bytes, text/plain)
2022-05-13 18:07 UTC, Jonathan Vasquez
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Jonathan Vasquez 2022-05-13 18:07:46 UTC
Created attachment 233897 [details]
[patch] serving poudriere packages privately

This change originally started as a drive by patch on github (https://github.com/freebsd/freebsd-doc/pull/66). Since then I decided to dive deeper into the docs and internalize the FDP a bit more and taking this as an opportunity to also improve my technical writing (as oppose to my informal technical writing :D).

Please let me know if there are any other improvements I should make. I've attached the diff (with a .txt extension as recommended in the FDP).

Thank you!
Comment 1 PauAmma freebsd_triage 2022-05-19 23:32:58 UTC
Comment on attachment 233897 [details]
[patch] serving poudriere packages privately

Thanks for coming back to it. That looks good to me besides the (very minor) quibble inline below, that's arguably a matter of taste.

>From 0e9a67f6781ed6641a39d1cfc3f41b6aec1b8266 Mon Sep 17 00:00:00 2001
>From: Jonathan Vasquez <jon@xyinn.org>
>Date: Fri, 13 May 2022 14:00:14 -0400
>Subject: [PATCH] handbook/ports: serving poudriere packages privately
>
>---
> .../content/en/books/handbook/ports/_index.adoc        | 10 ++++++++++
> 1 file changed, 10 insertions(+)
>
>diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc
>index cfe881e847..7c011abdc9 100644
>--- a/documentation/content/en/books/handbook/ports/_index.adoc
>+++ b/documentation/content/en/books/handbook/ports/_index.adoc
>@@ -1301,6 +1301,16 @@ custom: {
> }
> ....
> 
>+If exposing the package repository to the internet is not desired, the `file://` protocol can be used to point to the repository directly:

I'd say "prefix" instead of protocol here, since it's not a network protocol.

>+
>+[.programlisting]
>+....
>+custom: {
>+	url: "file:///usr/local/poudriere/data/packages/11amd64",
>+	enabled: yes,
>+}
>+....
>+
> [[ports-nextsteps]]
> == Post-Installation Considerations
> 
>-- 
>2.36.1
>
Comment 2 Jonathan Vasquez 2022-05-20 09:34:26 UTC
Hey PauAmma,

Thanks for that. I've always learned "file://" as being a protocol. You are right in that it's not a network protocol, but it is still a protocol on that it's the way in which you will be communicating. file:// could be communicating over the network (if you have a mounted network drive - but that's more of an OS abstraction). We could also call it a URI scheme or scheme for short if more comfortable. Here are some references of people calling it protocol as well on both UNIX and Windows worlds (where in Windows it's coming directly from Microsoft):

https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/jj710207(v=vs.85)

https://stackoverflow.com/questions/40070699/meaning-of-after-file-protocol-url

https://en.m.wikipedia.org/wiki/File_URI_scheme
Comment 3 Jonathan Vasquez 2022-05-20 09:36:03 UTC
For the Microsoft Link, the final ) is not being used if you click the link, manually copy it.
Comment 4 PauAmma freebsd_triage 2022-05-21 23:33:44 UTC
(In reply to Jonathan Vasquez from comment #2)

Fair enough. Could you remove the extra text (email headers etc.) from your patch and reupload, checking the "this is a patch" checkbox when you do?