hpr-tools/FAQ/FAQ.mkd
Dave Morriss 50edeccc88 Updates from previous repo
FAQ/FAQ.mkd, FAQ/Makefile: this version of the FAQ is now out of date
    and probably should be deleted.

InternetArchive/repair_item: script to upload missing shows after tie
    out errors during the normal upload; still under development.

InternetArchive/update_state: script to update show state in the
    'reservations' table in the database. Uses the CMS interface.

Link_Checker/scan_links: under development. Not currently usable.

Miscellaneous/fix_tags: audio metadata manipulation script. Recently
    added to this repo for convenience. Updates for 'experimental::try',
    the official Perl try/catch.

PostgreSQL_Database/add_hosts_to_show, PostgreSQL_Database/hpr_schema_2.pgsql,
    PostgreSQL_Database/nuke_n_pave.sh: an old experimental Pg database
    to take over from the previous MySQL version (from before 2023).
    Kept for reference; never implemented.
2024-06-14 16:00:04 +01:00

268 lines
12 KiB
Markdown

[%# FAQ.mkd <2021-04-01 15:17:14> version: 0.0.5 -%]
[% USE date -%]
---
title: Hacker Public Radio FAQ (draft) [% date.format(date.now,"%F") %]
subtitle: A collection of questions and answers with links to the HPR site
author: HPR Contributors
...
[%# {{{ Links %]
[% about = "http://hackerpublicradio.org/about.php" -%]
[% reqslot = "http://hackerpublicradio.org/request_a_slot.php" -%]
[% needtoknow = "http://hackerpublicradio.org/stuff_you_need_to_know.php" -%]
[% theme = "http://hackerpublicradio.org/theme.php" -%]
[% calendar = "http://hackerpublicradio.org/calendar.php" -%]
[% index = "http://hackerpublicradio.org/index_full.php" -%]
[% series = "http://hackerpublicradio.org/series.php" -%]
[% ccbysa3 = "http://creativecommons.org/licenses/by-sa/3.0/" -%]
[% maillist = "http://hackerpublicradio.org/maillist" -%]
[% freenode = "http://webchat.freenode.net/?channels=oggcastplanet" -%]
[% podrec = "http://hackerpublicradio.org/series.php?id=75" -%]
[% tags = "http://hackerpublicradio.org/tags.php" -%]
[%# }}} %]
# Hacker Public Radio FAQ [% date.format(date.now,"%F") %] {.unnumbered}
## What is Hacker Public Radio?
- Hacker Public Radio (HPR) is an Internet Radio show (podcast) that releases
shows (episodes) every weekday Monday through Friday.
- What differentiates HPR from other podcasts is that the shows are crowd
sourced from the community &mdash; fellow listeners like you. There is no
restriction on how long shows can be, nor on the topic you can cover, as long
as they are not spam and "are of interest to Hackers".
If you want to see what topics have been covered so far just have a look at
our [Archive]([% index %]). We also allow for shows to be grouped into
[series]([% series %]) so that hosts can go into more detail on a topic.
- Look at the [*About HPR*]([% about %]) page for a full description of *The HPR
Community*, *Free Culture*, *Governance* and our *Patrons*.
- A question on the mailing list in 2020 asked if HPR is a Content Publication
Network like YouTube, or is it a Podcast that random people contribute to? Or
to put it another way, is the host addressing the Internet in general or the
HPR Audience?
- The consensus of opinion is that HPR is a Podcast contributed to by the
community, not a Content Publication Network.
## What is a show?
- A show is your *audio* presentation (which we do not moderate), with an *intro*,
*outro*, a *title* and a *summary*.
- The *audio* is the recording you have made and sent in to HPR.
- The *intro* (introduction) is a piece of audio introducing the show. See
[*HPR Theme Music*]([% theme %]) for details. The components are:
- a synopsis taken from the details submitted with the show (added
automatically)
- acknowledgement of our hosting provider (added automatically)
- HPR introduction music, can be added automatically or by you
- The *outro* is added automatically, but you can add it yourself if you
want. It must contain the HPR outro music and the text you will find on the
[*HPR Theme Music*]([% theme %]) page.
- Each show needs a *title* to describe what it is about.
- Similarly, a *summary* helps to add more information describing the show so a
potential listener can decide whether to listen to it or not.
- Each show is expected to have certain mandatory attributes listed
[below][What are the mandatory elements of an HPR show?].
- HPR shows are usually expected to be informative or educational, and as such
some sort of accompanying written material is highly desirable. This might
consist of brief notes, links to relevant web sites, or possibly longer
notes and examples. Photographs, diagrams and example files are also welcome
if the host feels it helps to get the message across.
- Shows are released under a [Creative Commons Attribution-ShareAlike 3.0
Unported]([% ccbysa %]) license. See [*Stuff you need to know*]([%
needtoknow %]) for much more detail about this and related issues.
- As a contributor you can choose when your show will be released. We only
release one show a day, during week days, but if a slot is free you can claim it.
Go to the [*calendar*]([% calendar %]) page to do this. You need to have
your show ready to upload before you reserve a slot though.
## Can I submit a show made for another podcast?
- Strictly, no. Shows are expected to have been made exclusively for HPR.
- However, we support promoting new podcasts and other creative commons
material. If you record a show of your own in which you introduce the other
podcast, perhaps explaining why it is important, and giving links to the
feed, you may include an example episode.
- A series exists [*Podcast recommendations*]([% podrec %]), which can be used
for such shows.
## What defines a show as being "*Produced for Hacker Public Radio*"?
- If you create material and post it first on HPR then it meets the
requirements of "*being produced for HPR*". That means once you upload it to
the HPR server you can publish it anywhere else you like.
## What are the mandatory elements of an HPR show?
- See [*Picking a slot for your show*]([% reqslot %]) for the full details of
how to submit a show and what information is required.
- A quick summary of the main components is:
- A show title
- A summary of what the show is about
- The *explicit*/*clean* flag
- License
- Show notes
- Tags
- Audio
## What are tags?
- We are trying to maintain a collection of tags to allow people to find shows
on the same (or similar) topic.
- Tags are simple words or short phrases describing aspects of a show such as
what topics are covered in it. To get hints about what tags have already
been used you can view all the current tags in alphabetical order on this
page: [Tag summary]([% tags %])
- Some examples are: <b>android</b>, <b>creative commons</b> and
<b>gaming</b>.
- Are there any tags that are best avoided?
## Is it OK if I don't include notes with my show?
- **Please don't do that**. It is important to provide good show notes for
reasons described on the [*Picking a slot for your show*]([% reqslot %])
page:
- They provide the listeners with more information on the topic your show
is covering
- They ensure your show gets posted on time (the volunteers don't have to
make notes for you)
- They encourage people to download your show
- They allow your show to be indexed by search engines
- They make your show accessible to the deaf and hard of hearing
## How do I include photographs or other files with my show?
- TBA
## What is and is not edited in a show after submission?
- We don't listen to the audio before posting a show to the website, so we
don't change the content.
- Unless you have done so and told us you have, we add an introduction to the
audio announcing what it is. Similarly we add an *outro*. This is not
<u>editing</u> since we don't change the content.
- We may make changes to the show title, summary or tags. Usually these are
minor changes such as spelling corrections. The intention is not any sort of
censorship, merely to make these items more understandable or easier to
index.
- Depending on the form the show notes take we may modify these.
- If what is submitted is plain text we convert it to Markdown in order to
generate HTML.
- If the notes are one of the permitted markup formats (mostly Markdown
flavours) we may adjust this to ensure that valid HTML is generated.
- If the notes are HTML we run them through an HTML checker and correct
any mistakes it highlights.
- We may correct spelling, grammar and punctuation if this clarifies
anything which might otherwise be unclear.
- If despite the request for show notes of some kind, none are provided,
we may add notes which help to clarify the content of the show. This may
be done after the show is released (when we have had a chance to listen
to it).
- We are working on the production of reports about any changes made, which
will be sent to the host after we have processed the show.
- We may make changes to a show's metadata if the host requests it (see the
item on [fixing errors after upload][If I notice an error in my show's
details how can it be fixed?]).
- If a show contains links to resources which disappear after a period of
time, we may at some future time change the notes to refer to any *Wayback
Machine* copy that can be found.
## What are some common errors in show notes?
It depends on the note format to some extent:
### HTML notes
- It's very easy to hand-write bad HTML. That's why we use an HTML checker on
it, and fix the errors it reports.
- A common fault is to write `<code><pre>` to define a pre-formatted block
of text using a fixed-width font. However it's illegal because the `<pre>`
tag can't be enclosed in other tags like `<code>`. Use `<pre><code>`
instead.
### Markdown notes
- This is quite a forgiving format. Some people embed HTML in the Markdown,
and the HTML used suffers from some of the issues discussed in this
document. These are *much* harder to spot. The HTML checker can't really
help unless it's run on the output from Pandoc.
### General errors
- Spelling is often an issue in notes. As the notes are processed they are
edited in the Vim editor with the spell check option turned on. In most
cases spelling problems flagged by Vim are corrected.
- Grammar and punctuation can also be issues. We do not have very effective
grammar checking tools in the note preparation workflow. Modifications may
be made to split up extra-long (often *comma-spliced*) sentences,
rationalise the use of capital letters and similar.
## If I notice an error in my show's details how can it be fixed?
- The HPR administrators can make changes to show titles, summaries, notes and
so forth. Ideally send an email to `admin` at `hackerpublicradio.org`
explaining what the problem is and we'll fix it for you. We'll also ensure
that the changes are propagated to the relevant page on archive.org.
- Don't be tempted to send in your corrections as a comment. Comments are not
propagated to archive.org, so people referring to that copy will not see
the changes.
## Does `hobbypublicradio.com` have anything to do with HPR?
- Some environments prevent access to sites which use the word `'hacker'` or
`'hackers'` in their names (or content in extreme cases). The site names
`hobbypublicradio.{com,net,org}` have been created, which link to the main
HPR site, in order to get around this restriction.
- See the mailing list thread here:
<http://hackerpublicradio.org/pipermail/hpr_hackerpublicradio.org/2015-February/013267.html>
## How can I talk to other HPR hosts and listeners?
- You have a number of choices:
- The mailing list <hpr@hackerpublicradio.org> is where various policy
matters are discussed and announcements made. You need to be a member of
the list to post to it. Visit the [*listinfo page*]([% maillist %]) to
sign up.
- You can join the **#oggcastplanet** channel on IRC. Visit the
[freenode.net]([% freenode %]) network to sign up.
- A number of HPR messages may be found on Twitter (tag **#hpr**) and
Mastodon (tag **#hpr**).
- **TBA - Matrix? Telegram?**
- An HPR tradition exists where we record a 26-hour show at the turn of
the year celebrating the arrival of the New Year around the world. We
use Mumble to record the show and anyone can connect to the Mumble
server and speak to other HPR listeners and hosts. The recording is used
to make multiple shows which are released when they are ready.
[%#
vim: syntax=markdown:ts=8:sw=4:ai:et:tw=78:fo=tcqn:fdm=marker:com+=fb\:-
%]