diff --git a/README.md b/README.md index 7e9136b..22e6d3d 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/build.sh b/build.sh index 96c2b69..6655313 100755 --- a/build.sh +++ b/build.sh @@ -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" diff --git a/builder.sh b/builder.sh new file mode 100755 index 0000000..bb0e746 --- /dev/null +++ b/builder.sh @@ -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 diff --git a/modules/ROOT/pages/_partials/con_cups-useful-tricks.adoc b/modules/ROOT/pages/_partials/con_cups-useful-tricks.adoc index 315009a..d14fb8b 100644 --- a/modules/ROOT/pages/_partials/con_cups-useful-tricks.adoc +++ b/modules/ROOT/pages/_partials/con_cups-useful-tricks.adoc @@ -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 -v -m -E where `` and `` are underscored strings from previous commands and `` 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. diff --git a/modules/ROOT/pages/wine.adoc b/modules/ROOT/pages/wine.adoc index f296662..f74eba4 100644 --- a/modules/ROOT/pages/wine.adoc +++ b/modules/ROOT/pages/wine.adoc @@ -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]. diff --git a/preview.sh b/preview.sh index 4270107..6655313 100755 --- a/preview.sh +++ b/preview.sh @@ -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"