hank-test/quick-docs
1
0
Fork 0
mirror of https://pagure.io/fedora-docs/quick-docs.git synced 2024-11-24 21:35:17 +00:00
Code Issues 1 Projects Releases Packages Wiki Activity Actions

Merge branch 'master' of ssh://pagure.io/fedora-docs/quick-docs

Browse source
This commit is contained in:
Ankur Sinha (Ankur Sinha Gmail) 2022-09-24 13:51:58 +01:00
commit c6cdc98d8d
No known key found for this signature in database
GPG key ID: F8D8C0BEBAC898BD
6 changed files with 325 additions and 191 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
README.md
View file

@ -34,21 +34,22 @@ markup language. You may want to look at:
## Local preview
This repo includes scripts to build and preview the contents of this repository.
This repo includes a script to build, watch and preview the contents of this repository.
**NOTE**: Please note that if you reference pages from other repositories, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions.
Both scripts use podman in F30 and above. Please make sure you have podman installed on your system (you can also use Docker, but on Fedora podman is recommended).
The script uses podman. Please make sure you have podman installed on your system (you can also use Docker, but on Fedora podman is recommended).
### Installing podman on Fedora
### Installing dependencies on Fedora
```
$ sudo dnf install podman
$ sudo dnf install podman inotify-tools
```
To build and preview the site, run:
To build, watch and preview the site, run:
```
$ ./build.sh && ./preview.sh
$ ./builder.sh
```
The result will be available at http://localhost:8080
and automatically regenerated when the repo contents change.

53
build.sh
View file

@ -1,52 +1,3 @@
#!/bin/sh
#!/bin/bash
image="docker.io/antora/antora"
cmd="--html-url-extension-style=indexify site.yml"
if uname | grep -iwq darwin; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo ""
echo "This build script is using Docker container runtime to run the build in an isolated environment."
echo ""
docker run --rm -it -v "$(pwd):/antora" "${image}" ${cmd}
elif uname | grep -iq linux; then
# Running on Linux.
# there isn't an antora/aarch64 container, antora can be installed locally
# Check whether podman is available, else faill back to docker
# which requires root.
if [ -f /usr/local/bin/antora ]; then
/usr/local/bin/antora "${cmd}"
elif uname -m | grep -iwq aarch64; then
echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`"
elif [ -f /usr/bin/podman ]; then
echo ""
echo "This build script is using Podman to run the build in an isolated environment."
echo ""
podman run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}
elif [ -f /usr/bin/docker ]; then
echo ""
echo "This build script is using Docker to run the build in an isolated environment."
echo ""
if groups | grep -wq "docker"; then
docker run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}
else
echo "You might be asked for your password."
echo "You can avoid this by adding your user to the 'docker' group,"
echo "but be aware of the security implications."
echo "See https://docs.docker.com/install/linux/linux-postinstall/"
echo ""
sudo docker run --rm -it -v "$(pwd):/antora:z" "${image}" ${cmd}
fi
else
echo ""
echo "Error: Container runtime haven't been found on your system. Fix it by:"
echo "$ sudo dnf install podman"
exit 1
fi
fi
echo "Deprecated. Use the builder.sh script instead"

218
builder.sh Executable file
View file

@ -0,0 +1,218 @@
#!/bin/bash
# script to watch source directory for changes, and automatically call build.sh to rebuild as required.
image="docker.io/antora/antora"
cmd="--html-url-extension-style=indexify site.yml"
srcdir="modules"
buildir="public"
previewpidfile="preview.pid"
inotifyignore=".git*"
watch_and_build () {
if ! command -v inotifywait > /dev/null
then
echo "inotifywait command could not be found. Please install inotify-tools."
echo "On Fedora, run: sudo dnf install inotify-tools"
stop_preview_and_exit
else
# check for git
# required to get ignorelist
if ! command -v git > /dev/null
then
echo "git command could not be found. Please install git."
echo "On Fedora, run: sudo dnf install git-core"
stop_preview_and_exit
else
# Get files not being tracked, we don't watch for changes in these.
# Could hard code, but people use different editors that may create
# temporary files that are updated regularly and so on, so better
# to get the list from git. It'll also look at global gitingore
# settings and so on.
inotifyignore="$(git status -s --ignored | grep '^!!' | sed -e 's/^!! //' -e 's:/:\*:' | tr '\n' '|')${inotifyignore}"
fi
while true
do
echo "Watching current directory (excluding ${inotifyignore}) for changes and re-building as required. Use Ctrl C to stop."
inotifywait -q --exclude "($inotifyignore)" -e modify,create,delete,move -r . && echo "Change detected, rebuilding.." && build
done
fi
}
build () {
if [ "$(uname)" == "Darwin" ]; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo ""
echo "This build script is using Docker container runtime to run the build in an isolated environment."
echo ""
docker run --rm -it -v $(pwd):/antora $image $cmd
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then
# Running on Linux.
# Check whether podman is available, else faill back to docker
# which requires root.
if [ -f /usr/bin/podman ]; then
echo ""
echo "This build script is using Podman to run the build in an isolated environment."
echo ""
podman run --rm -it -v $(pwd):/antora:z $image $cmd --stacktrace
elif [ -f /usr/bin/docker ]; then
echo ""
echo "This build script is using Docker to run the build in an isolated environment."
echo ""
if groups | grep -wq "docker"; then
docker run --rm -it -v $(pwd):/antora:z $image $cmd
else
echo ""
echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."
echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."
echo ""
sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd
fi
else
echo ""
echo "Error: Container runtime haven't been found on your system. Fix it by:"
echo "$ sudo dnf install podman"
exit 1
fi
fi
}
start_preview () {
# clean up a preview that may be running
stop_preview
# always run an initial build so preview shows latest version
build
if [ "$(uname)" == "Darwin" ]; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo "The preview will be available at http://localhost:8080/"
docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx
elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then
# Running on Linux.
# Fedora Workstation has python3 installed as a default, so using that
echo ""
echo "The preview is available at http://localhost:8080"
echo ""
pushd "${buildir}" > /dev/null 2>&1
python3 -m http.server 8080 &
echo "$!" > ../"${previewpidfile}"
popd > /dev/null 2>&1
fi
}
stop_preview () {
if [ -e "${previewpidfile}" ]
then
PID=$(cat "${previewpidfile}")
kill $PID
echo "Stopping preview server (running with PID ${PID}).."
rm -f "${previewpidfile}"
else
echo "No running preview server found to stop: no ${previewpidfile} file found."
fi
}
stop_preview_and_exit ()
{
# stop and also exit the script
# if stop_preview is trapped, then SIGINT doesn't stop the build loop. So
# we need to make sure we also exit the script.
# stop_preview is called before other functions, so we cannot add exit to
# it.
stop_preview
exit 0
}
usage() {
echo "$0: Build and preview Fedora antora based documentation"
echo
echo "Usage: $0 [-awbpkh]"
echo
echo "-a: start preview, start watcher and rebuilder"
echo "-w: start watcher and rebuilder"
echo "-b: rebuild"
echo "-p: start_preview"
echo "-k: stop_preview"
echo "-h: print this usage text and exit"
echo
echo "Maintained by the Fedora documentation team."
echo "Please contact on our channels: https://docs.fedoraproject.org/en-US/fedora-docs/#find-docs"
}
# check if the script is being run in a Fedora docs repository
if [ ! -e "site.yml" ]
then
echo "site.yml not be found."
echo "This does not appear to be a Fedora Antora based documentation repository."
echo "Exiting."
echo
usage
exit 1
fi
if [ $# -lt 1 ]
then
echo "No options provided, running preview with watch and build."
echo "Run script with '-h' to see all available options."
echo
echo
trap stop_preview_and_exit INT
start_preview
watch_and_build
stop_preview
fi
# parse options
while getopts "awbpkh" OPTION
do
case $OPTION in
a)
# handle sig INT to stop the preview
trap stop_preview_and_exit INT
start_preview
watch_and_build
stop_preview
exit 0
;;
w)
watch_and_build
exit 0
;;
b)
build
exit 0
;;
p)
start_preview
echo "Please run ./builder.sh -k to stop the preview server"
exit 0
;;
k)
stop_preview
exit 0
;;
h)
usage
exit 0
;;
?)
usage
exit 1
;;
esac
done

93
modules/ROOT/pages/_partials/con_cups-useful-tricks.adoc
View file

@ -3,9 +3,27 @@
== How to find out whether my printer is capable of driverless printing?
* look for AirPrint among device specification
* https://www.pwg.org/printers/[Officially certified printers for IPP Everywhere]
* check xref:_how_to_setup_cups_temporary_queues_with_network_printer[manual] for enabling CUPS temporary queues - if your printer is seen in the end in CUPS commands that way, your printer is capable of driverless printing
Network printers have the prerequisites - enablement of IPP port on the printer is the minimum, mDNS is required for automatic printer discovery by `libcups`.
* [command]`ipptool` command which sends IPP Get-Printer-Attributes request to the network printer passes:
----
$ ipptool -tv ipp://printer.example.com:631/ipp/print get-printer-attributes.test
"/usr/share/cups/ipptool/get-printer-attributes.test":
Get-Printer-Attributes:
attributes-charset (charset) = utf-8
attributes-natural-language (naturalLanguage) = en
printer-uri (uri) = ipp://printer.example.com:631/ipp/print
requested-attributes (1setOf keyword) = all,media-col-database
Get printer attributes using get-printer-attributes [PASS]
...
----
, where `printer.example.com` is the hostname or IP of your network printer,
* look for AirPrint among device specification,
* https://www.pwg.org/printers/[Officially certified printers for IPP Everywhere],
* check xref:_how_to_setup_cups_temporary_queues_with_network_printer[manual] for enabling CUPS temporary queues - if your printer is seen in the end in CUPS commands that way, your printer is capable of driverless printing,
* [USB devices only] check for IPP over USB (xref:_how_to_find_out_if_my_usb_device_supports_ipp_over_usb[manual] here).
== How to find out my multifunction device or standalone scanner is capable of driverless scanning?
@ -178,6 +196,75 @@ $ lpadmin -p <name> -v <device_uri> -m <driver> -E
where `<device_uri>` and `<driver>` are underscored strings from previous commands and `<name>` is a print queue name, which is chosen by you.
== How to install a printer via printer application in SNAP and making it available for CUPS
Currently printer applications are available in SNAPs on Fedora. I'm planning to release them as RPMs, but the code base will be the same, so its testing can happen even with SNAPs.
* install snapd,
First we have to install snapd for testing purposes:
----
$ sudo dnf -y install snapd
$ sudo ln -s /var/lib/snapd/snap /snap
$ snap version
----
If the installation had been successful, the last command will show snapd's version.
* install and run printer application,
First the SNAP with printer application has to be installed and started by the commands below. All printer applications are available in SNAP Store under the same names as they are at https://github.com/orgs/OpenPrinting/repositories[OpenPrinting repositories]. We will use [filename]`ps-printer-app` printer application in the next steps.
----
$ sudo snapd install --edge ps-printer-app
$ sudo snapd run ps-printer-app
----
* go to http://localhost:8000,
After starting the printer application its web interface becomes available at http://localhost:8000 - if user installs and runs another printer application, it will become available at localhost on the next port (8001). The printer application can contain several printers (as [filename]`cupsd` does).
* click on `Add Printer` on the main page,
* choose the printer's name,
* select the found device or choose `Network printer` from `Device` scroll menu and provide hostname or IP of the device,
* choose to auto-detect driver or select the driver by yourself,
* click on `Add Printer`,
* now the printer should be available at least on localhost via mDNS (if [filename]`avahi-daemon` is running and `nss-mdns` is installed)- check it by [filename]`avahi-browse`(`avahi-tools` has to be installed):
----
$ avahi-browse -avrt
...
= lo IPv4 HP Laserjet M1536 _ipp._tcp local
hostname = [fedora-2.local]
address = [127.0.0.1]
port = [8000]
txt = ["Scan=F" "PaperMax=legal-A4" "Fax=F" "product=(HP LaserJet M1536dnf MFP Postscript (recommended))" "mopria-certified=1.3" "priority=0" "qtotal=1" "txtvers=1" "Duplex=T" "Color=F" "TLS=1.2" "URF=V1.5,W8,PQ3-4-5,DM1,FN3,IS0-20,MT1-5-6-3,OB10,RS300-600" "UUID=24837a30-5f87-3ac9-6d85-086d486092dd" "pdl=image/pwg-raster,image/urf,application/vnd.printer-specific,application/pdf,application/postscript,image/jpeg,image/png" "note=" "adminurl=http://fedora-2.local:8000/HP_Laserjet_M1536/" "ty=HP LaserJet M1536dnf MFP Postscript (recommended)" "rp=ipp/print/HP_Laserjet_M1536"]
...
----
* and by `lpstat -e`:
----
$ lpstat -e
...
HP_Laserjet_M1536
...
----
The available printing options for the printer installed via printer application can be checked with [filename]`lpoptions` command:
----
$ lpoptions -p HP_Laserjet_M1536 -l
PageSize/Media Size: 184.15x260mm 195.09x269.88mm A4 A5 B5 DoublePostcardRotated Env10 EnvC5 EnvDL EnvMonarch Executive FanFoldGermanLegal ISOB5 Legal *Letter Postcard roc16k Custom.WIDTHxHEIGHT
InputSlot/Media Source: *Auto Tray1 Auto
MediaType/Media Type: *Unspecified Stationery Light6074 MidWeight96110 Heavy111130 ExtraHeavy131175 MonochromeLaserTransparency Labels StationeryLetterhead Envelope StationeryPreprinted Prepunched Colored Bond StationeryRecycled Rough Vellum
cupsPrintQuality/cupsPrintQuality: Draft *Normal High
ColorModel/Output Mode: *Gray
Duplex/Duplex: *None DuplexNoTumble DuplexTumble
OutputBin/OutputBin: *FaceDown
----
== How to install a scanner
Scanners in Linux don't have to be installed the same way as printers are if they are in the same network or connected via USB - you just need *sane-backends* to be installed and any scanning application will communicate with scanner/multifunction device via the backend which supports the scanner.

120
modules/ROOT/pages/wine.adoc
View file

@ -8,113 +8,17 @@ API on top of X and OpenGL.
Wine emulates the Windows runtime environment by translating Windows system calls
into POSIX-compliant system calls, recreating the directory structure of Windows systems,
and providing alternative implementations of Windows system libraries,
system services through https://wiki.winehq.org/Wineserver[wineserver]
and various other components such as Internet Explorer, the Windows Registry Editor, and msiexec.
system services through https://wiki.winehq.org/Wineserver[wineserver].
== Packages
Fedora's Wine packages are split up to allow for smaller installations.
The `wine` meta package will bring with it the most important components
of Wine. Expert users may want to pick specific components from the list
below:
of Wine.
Expert users may want to pick specific components from the list
https://packages.fedoraproject.org/pkgs/wine/[here].
[cols=",",]
|=======================================================================
|*name* |''' summary '''
|_wine_ |Meta package
|_wine-alsa_ |ALSA sound support for wine
|_wine-arial-fonts_ |Arial fonts provided by wine-staging
|_wine-capi_ |ISDN support for wine
|_wine-cms_ |Color Management for wine
|_wine-common_ |Common wine files and scripts
|_wine-core_ |Wine core package
|_wine-courier-fonts_ |Wine Courier font family
|_wine-desktop_ |Desktop integration features
|_wine-devel_ |Wine development environment
|_wine-filesystem_ |Filesystem directories and basic configuration for
wine
|_wine-fixedsys-fonts_ |Wine Fixedsys font family
|_wine-fonts_ |Wine font meta package
|_wine-ldap_ |LDAP support for wine
|_wine-marlett-fonts_ |Wine Marlett font family
|_wine-ms-sans-serif-fonts_ |Wine MS Sans Serif font family
|_wine-openal_ |OpenAL sound support for wine
|_wine-opencl_ |OpenCL support for wine
|_wine-pulseaudio_ |PulseAudio support for wine
|_wine-small-fonts_ |Wine Small font family
|_wine-symbol-fonts_ |Wine Symbol font family
|_wine-systemd_ |systemd configuration for the wine binfmt handler
|_wine-system-fonts_ |Wine System font family
|_wine-sysvinit_ |SysV initscript for the wine binfmt handler
|_wine-tahoma-fonts_ |Wine Tahoma font family
|_wine-tahoma-fonts-system_ |Wine Tahoma font family system integration
|_wine-twain_ |Twain (image scanning) support for wine
|_wine-wingdings-fonts_ |Wine Wingdings font family
|_wine-wingdings-fonts-system_ |Wine Wingdings font family system
integration
|=======================================================================
Additional documentation is provided via the ''wine-docs '' package.
[[available-versions]]
== Available versions
Fedora applies fixes and features from the *wine-staging* project. EPEL
packages do not use wine-staging patches.
*Current versions of Wine in Fedora:*
[cols=",",]
|=================
|Fedora 33(pre-release) |5.16
|Fedora 29 |4.5
|Fedora 28 |3.4
|Fedora 27 |3.4
|Fedora 26 |3.4
|EPEL 7 |3.0
|=================
Newer versions may be available in the corresponding `updates-testing`
repositories.
[[testing-versions]]
== Testing Versions
[cols=",",]
|=================
|Fedora 28 |3.5
|Fedora 27 |3.5
|Fedora 26 |3.5
|=================
The current versions of the Wine packages can also be seen on the https://packages.fedoraproject.org/pkgs/wine/wine/[Fedora packages application].
[[bugs-and-problems]]
== Bugs and problems
@ -126,7 +30,7 @@ up to date.
dnf upgrade
....
Also check if a newer version is available in updates-testing.
Also check if a newer version is available in the https://fedoraproject.org/wiki/QA:Updates_Testing[updates-testing] repository.
....
dnf --enablerepo=updates-testing update wine
@ -168,15 +72,3 @@ IMPORTANT: Do not file bugs in the Winehq.org bugzilla unless told to do so.
If you really think that your bug is Fedora-related, file a bug against
the Wine component in https://bugzilla.redhat.com[Fedora's bug tracking
system].
[[updates-testing]]
== Updates-Testing
If you use the version of wine in the updates-testing repository then
please log into https://bodhi.fedoraproject.org/updates/?packages=wine[bodhi] and
comment on the build, including any problems that may be in the
packaging, naming, or elsewhere. The build needs positive karma to be
pushed to the updates repository.
See a typo, something missing or out of date, or anything else which can be
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs[Pagure].

19
preview.sh
View file

@ -1,18 +1,3 @@
#!/bin/sh
#!/bin/bash
if [ "$(uname)" = "Darwin" ]; then
# Running on macOS.
# Let's assume that the user has the Docker CE installed
# which doesn't require a root password.
echo "The preview will be available at http://localhost:8080/"
docker run --rm -v "$(pwd):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx
elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then
# Running on Linux.
# Fedora Workstation has python3 installed as a default, so using that
echo ""
echo "The preview is available at http://localhost:8080"
echo ""
cd ./public
python3 -m http.server 8080
fi
echo "Deprecated. Use the builder.sh script instead"