Markdown でマニュアルの作成

Markdown でマニュアルの作成

Markdown 楽だよねってことで、Markdown で業務マニュアル作成することにしたので、その手順のまとめ

VSCode の Markdown 用の拡張をいくつかインストールしておく

• Markdown All in One、目次の作成と章番号の追加など
• Markdown Preview Enhanced、Markdown のプレビュー
• Markdownlint、書式の確認
• Markdown PDF、PDFへの出力

目次

• 1. マニュアルの記述
• 2. 章番号と目次の作成
• 3. PDF化
• 4. 余談

1. マニュアルの記述

Markdownを使ってマニュアルを作成していく。

mdファイルの上で右クリックして、「Markdown Preview Enhanced Open Preview to the Side」でプレビュー画面が右ペインに表示される。

mdファイルを編集すれば自動的に更新されていくのでWYSIWYGで編集できる。

# を使って章番号を設定しておくと VSCode の左にあるアウトラインから章に移動することができる。便利

編集内容に問題があれば Markdownlint が下線で警告してくれるので、クリックすると修正内容を提案してくれる。

画像などは必要なところに直接コピペすると、![alt text](image-1.png) という感じで貼り付けてくれる。

便利だけど理想的には images ディレクトリを作成しておき、そこに保存をして、 ![画像名](画像ファイルへの相対パス) な感じで修正したほうがいいかもしれない。

2. 章番号と目次の作成

VSCode のコマンドパレットを開いて(Windows:Ctrl+Shift+p、Mac:Shift+Command+p) Markdown All In One のコマンドで章番号、目次の作成できる。

章番号の追加、更新は Markdown All in One: Add/Update section numbers

章番号、目次に含めたくない場合は <!-- omit in toc --> を見出し行の前にいれておく。

見出しを追加更新した場合には再度Add/Update section numbersを実行して章番号を更新する。

目次は Markdown All in One: Create Table of Contents で目次を作成してくれる。

作成した目次はリンクになっているのでそこから対象へ移動することができる。

3. PDF化

作成したマニュアルをPDF化したい場合には、mdファイルを右クリックして「Markdown PDF: export (PDF)」でPDFファイルにすることができる。

4. 余談

もともとは Word で作成するつもりだったのだが、ざっくり見出しを作った時点で7章、100項目以上になりそうで、サブ文章に分けることとか、アウトラインで編集するなど考えたのだが差分も取りにくいし画像のいちとかレイアウトを考えるのも大変ということで Markdown で書くことにした。

Wordのアウトラインモードで画像や表の扱いがらくになるとか、履歴差分がわかりやすくなる方法などがあればもうちょっとWordも検討対象になったのだが。

GitHub Webhooks をつかて push したらデプロイ

以前の記事でgit の hooks を使って push したらWebサーバにデプロイする環境を構築してみたがやっぱり push 先が2つになるのはめんどくさいので GitHub に push したらWebサーバにもデプロイされるようにしたい。

• リポジトリはプライベート
• Webhook でデプロイ先のURLへアクセス
• URLにアクセスされたら、git pull を実行

という単純なものにするのでセキュリティなどは考慮しない。

ただこの場合 apache の権限で git pull されることになるので、Webページのファイル、ディレクトリ権限が apache で読み書きできるものになる。

apache へ ssh キーの設定

/etc/passwd ファイルを確認して apache のホームディレクトリを探し、そこに .ssh ディレクトリを作成して、鍵ファイルを作成する。

# cat /etc/passwd | grep apache
apache:x:48:48:Apache:/usr/share/httpd:/sbin/nologin
# cd /usr/share/httpd/
# mkdir .ssh
# ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa): /usr/share/httpd/.ssh/id_rsa
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /usr/share/httpd/.ssh/id_rsa.
Your public key has been saved in /usr/share/httpd/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:wa8n56*************************lC3oon9kGD8 root@example.com
The key's randomart image is:
+---[RSA 3072]----+
|        .+o      |
|       . .o      |
|   . . .o+.o     |
|. . * . *o+.     |
|.= = = =Soo      |
|o = B E .. .     |
| . * B oo + o    |
|  o   .  * +..   |
|   ...    +o.    |
+----[SHA256]-----+
# chown -R apache:apache /usr/share/httpd/.ssh
# chmod -R 700 /usr/share/httpd/.ssh
# cat /usr/share/httpd/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAA(略)GWVQM9fcb0VXJhTM= root@example.com
#

鍵ファイルを作成したら公開鍵をコピーして、GitHub のアカウントから「Settings」を開き、「SSH and GPG keys」の「SSH Keys」の「New SSH Key」ボタンを押す。

SSH Keyの登録画面になるので、「Title」に識別しやすい名前をつけて、先ほど作成した id_rsa.pub の中身を「Key」貼り付けて、「Add SSH Key」をクリックする。

これでこの現在のアカウントに新しい SSH Key が登録される。

更新用URLの作成

ごく簡単なphpスクリプトで更新用のphpファイルを作成する。

アクセスされても更新されるだけのURL

<?php
system('cd /path/to/web_directory');
system('git pull origin master');

作成した php ファイルの URL にアクセスして、「Already up to date.」とかのメッセージが表示されていることを確認する。

Webhooks の設定

GitHub の資料がわかりやすい。

Webhooks を設定したいリポジトリを開いて、リポジトリの「Settigs」を開き、「Webhooks」を開く。

「Add Webhook」ボタンをクリックして、「Payload URL」に先ほど作成した更新用のURLを貼り付ける。

特にデータのやり取りなどがあるわけでもないのでその他の場所はそのままにして「Add webhook」で作成する。

確認

以上でできたはずなので動作確認。

webhook を設定する前に更新用URLを開いてページが更新されることを確認しておけば確実。

あとは GitHub に push すれば自動的に更新される。

git の hooks を使って push したらWebサーバにデプロイする

gitでWebページを作成しているときに、push したら公開サーバにデプロイされるようにしたいというのが目的

ワーキングリポジトリで作業した結果を公開サーバに作成した bare リポジトリに push して、bare リポジトリの web-hooks を使用して公開サーバの公開リポジトリで pull をする。

直接公開リポジトリに push することもできるが、git はそれを奨励していなくて、bare リポジトリを使用するようにメッセージが表示される。

通常の git リポジトリはファイルを持っているが、bare リポジトリはリポジトリの更新情報だけを持っている。

ssh で鍵を作成してリモートサーバへ登録する

sshの証明書を使って自動ログインできるようにしておく。

パスフレーズはなしにしたほうが楽…っ

リポジトリの作成

リモートのサーバにログインして、

# git clone --bare git@github.com:hoge/hage.git hage.git

で作成、bare リポジトリは慣例的に .git をつけるらしい。

公開用リポジトリを作成、公開リポジトリは bare リポジトリから clone しておく

# git clone /path/to/hage.git hage
# git remote -v 
origin  /path/to/hage (fetch)
origin  /path/to/hage (push)

/path/to/hage ディレクトリに hooks ディレクトリがあり、そこに各種 hook に使用するファイルのサンプルがある。

リポジトリに push されたときに hook が動いてほしいので、post-receive を使用する。多分ないので新規に作成する。

post-receive の記述

#!/bin/sh

# ないと「remote: fatal: Not a git repository: '.'」エラーが出る、今回のハマりポイント
unset GIT_DIR  

cd /path/to/hage
git pull origin master

作成した post-receive ファイルには実行権限を設定しておく

# chmod +x post-receive

ワーキングリポジトリの remote 設定

作業用のマシンで設定を行う。

今まで github を使って作業していたのなら、origin に github が設定されているはず。

ここに公開サーバに作成しいた bare リポジトリを push 先に追加する

# git remote -v
origin git@github.com:hoge/hage.git/ (fetch)
origin git@github.com:hoge/hage.git/ (push)
# git remote add hage ssh:svname/path/to/hage.git
# git remote -v
hage ssh:svname/path/to/hage.git (fetch)
hage ssh:svname/path/to/hage.git (push)
origin git@github.com:hoge/hage.git/ (fetch)
origin git@github.com:hoge/hage.git/ (push)

これで git push origin master で github へ、git push hage master で公開サーバの bare リポジトリに push されるようになる。

そして hage へ push したときには hooks の post-receive が動いて、公開リポジトリから pull してくれるので push コマンド一発で公開できるようになる。

AWS Tools for PowerShell を PowerShell にインストールしてファイルの一括アップロード

AWS Tools installer のインストール

AWS Cli と AWS Tools for PowerShell でも構文違うの面倒くさいなぁと思いつつ

PS C:\WINDOWS\system32> Install-Module -Name AWS.Tools.Installer 
続行するには NuGet プロバイダーが必要です
PowerShellGet で NuGet ベースのリポジトリを操作するには、'2.8.5.201' 以降のバージョンの NuGet プロバイダーが必要です。NuGet プロバイダーは 'C:\Program Files\PackageManagement\ProviderAssemblies' または
'C:\Users\ikeno\AppData\Local\PackageManagement\ProviderAssemblies'
に配置する必要があります。'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'
を実行して NuGet プロバイダーをインストールすることもできます。今すぐ PowerShellGet で NuGet
プロバイダーをインストールしてインポートしますか?
[Y] はい(Y)  [N] いいえ(N)  [S] 中断(S)  [?] ヘルプ (既定値は "Y"): y

信頼されていないリポジトリ
信頼されていないリポジトリからモジュールをインストールしようとしています。このリポジトリを信頼する
場合は、Set-PSRepository コマンドレットを実行して、リポジトリの InstallationPolicy
の値を変更してください。'PSGallery' からモジュールをインストールしますか?
[Y] はい(Y)  [A] すべて続行(A)  [N] いいえ(N)  [L] すべて無視(L)  [S] 中断(S)  [?] ヘルプ
(既定値は "N"):Y

PS C:\WINDOWS\system32> Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.S3 -CleanUp

確認
この操作を実行しますか?
対象 "AWS Tools version 4.1.346.0" に対して操作 "Install-AWSToolsModule" を実行しています。
[Y] はい(Y)  [A] すべて続行(A)  [N] いいえ(N)  [L] すべて無視(L)  [S] 中断(S)  [?] ヘルプ
(既定値は "Y"):
Installing module AWS.Tools.EC2 version 4.1.346.0
Installing module AWS.Tools.S3 version 4.1.346.0
PS C:\WINDOWS\system32>

IAM を使用してユーザを作成して「セキュリティ認証情報」からアクセスキーを生成する

アクセスキーを設定する

PS C:\> Set-AWSCredential `
>> -AccessKey [Accesskey] `
>> -SecretKey [秘密鍵] `
>> -StoreAs [プロファイル名、デフォルトなら default]

目的のファイルが有るフォルダに移動して

foreach ($f in Get-ChildItem ) {
   Write-S3Object -BucketName [S3バスケット名] `
   -File $f -Key [オブジェクト名]/$f -CannedACLName public-read -ProfileName [IAMプロファイル名]
}

参考：
AWS Tools for PowerShell とは何ですか? - AWS Tools for PowerShell

tor 経由で ssh でアクセス

tor はブラウザだけじゃなくて socks5 を設定することで ssh も使える

Tor Project | Downloadから「Download Tor Source Code」のリンクをクリックして、「Windows Expert Bundle」からファイルをダウンロードする。

ダウンロードしたzipファイルを適当なフォルダに展開する。自分は「C:\temp\torsocks」展開した。

コマンドプロンプトを管理者権限で開いて、以下のコマンドを実行

.\tor.exe --service install

「サービス」を見ると、「Tor Win32 Service」が登録されて、実行になっているはず。

Teratermの「プロキシ」で「type：SOCKS5」、「Hostname：localhost」、「Port number：9050」で、「URL」に「socks://localhost:9050」と設定される。

あとはふつうに Teraterm から ssh アクセスすれば、Tor 経由の ssh アクセスになるので、身元を追うことは基本的に不可能になる。

# サービスのインストール
tor.exe --service install   

# torrc ファイルを作成してサービス登録時に読み込みする
tor.exe --service insatll --options -f "c:\temp\torsocks\tor\torrc"

# サービスの削除
tor.exe --service remove

2021年暮れの CentOS6.6アップグレード作業

今更ながら CentOS 6.6 のアップグレード。すでに CentOS 6 系のサポートは 2020年11月30日でサポートが終了しているが、なんか手元に残っていたのでアップグレードをしてみた。

[root@hoge ~]# yum check-update
読み込んだプラグイン:fastestmirror, security
Determining fastest mirrors
YumRepo Error: All mirror URLs are not using ftp, http[s] or file.
 Eg. Invalid release/repo/arch combination/
removing mirrorlist with no valid mirrors: /var/cache/yum/x86_64/6/base/mirrorlist.txt
エラー: Cannot find a valid baseurl for repo: base

当然のことながらできない。

[base]
name=CentOS-$releasever - Base
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os&infra=$infra
#baseurl=http://mirror.centos.org/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6

#released updates
[updates]
name=CentOS-$releasever - Updates
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=updates&infra=$infra
#baseurl=http://mirror.centos.org/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6

mirrorlist をコメントアウトして、baseurl のコメントを外して、http://mirror.centos.org を https://vault.centos.org/ に変更する。
とりあえず、CentOS-Base.repo の base と updates 以外の項目は enable=0 にして無効にする。

[root@hoge yum.repos.d]# yum check-update
読み込んだプラグイン:fastestmirror, security
Determining fastest mirrors
 * rpmforge: mirrors.netix.net
https://vault.centos.org/centos/6/os/x86_64/repodata/repomd.xml: [Errno 14] problem making ssl connection

SSLでエラーがでる。証明書が古いので証明書を更新する。

適当なディレクトリに移動して、証明書をダウンロードして rpm でインストール。

[root@hgoe src]# wget --no-check-certificate https://vault.centos.org/6.10/updates/x86_64/Packages/ca-certificates-2020.2.41-65.1.el6_10.noarch.rpm
[root@hoge src]# rpm -Uhv  ca-certificates-2020.2.41-65.1.el6_10.noarch.rpm

他に P11-kit や nss、Openssl などのパッケージが必要になるかもしれないので必要に応じて vault あたりからダウンロードして、rpm でインストールする。

[root@hoge yum.repos.d]# yum check-update
読み込んだプラグイン:fastestmirror
Determining fastest mirrors
base                                                     | 3.7 kB     00:00
base/primary_db                                          | 4.7 MB     00:03

エラーが出なくなったので、アップグレードを行う。

[root@hoge yum.repos.d]# yum update -y
reboot

[root@hoge ~]# cat /etc/redhat-release
CentOS release 6.10 (Final)

6.10 にアップグレードされた。

ハイレゾ音源について

ハイレゾ音源とその再生についていろいろ調べた。目的はPC環境での再生について。

ハイレゾ音源とは

基本的にCD(16bit、44.1MHz)以上のビットレートの音源がハイレゾ音源になる。特に量子化ビット数は24bit以上が求められる。

フォーマットとして、WAVE、MP3、AAC、FLACなどがある。
非圧縮のWAVE、AIFF、可逆圧縮のFLAC、ALAC、非可逆圧縮のMQA、MP3、Ogg、AAC、

ハイレゾ音源で使用されることが多いのは FLAC だが、最近は MQA が使用されることも多い。

MQAは既存のCDなどでCD音質で聞くことができるが、対応機ならハイレゾで聞くことができるという特徴がある。MQA のほうが圧縮率が高いが非可逆で技術がクローズドなため、技術がオープンで可逆圧縮なFLACに対して長期で見た場合継続に疑問点が付く。

参考：https://rideonmarin.blogspot.com/2018/04/mqa-part15.html

MQAの対応には「MQAフルデコーダー」と「MQAレンダラー」があり、MQAレンダラーのみではMQAのデコードができず、「MQAコアデコーダー」と組み合わせて再生する。MQAレンダラーは対応のDACなどに、MQAコアデコーダーなどはPC上の再生ソフトなどに搭載される。MQAフルデコーダーは据え置きの再生機などに。

PCMとDSD

PCMはアナログ音声を波の高さで記録する、一般的にPCで使用される方式、DSDはアナログ音声を波の密度で記録するハイレゾ音源で使用されることが増えている形式。

PCMは編集可能だが、DSDは編集が難しく、一発どりや最後のマスタリングで使用されることが多い。またDSDは再生にそれ用のアプリと機器が必要になり、USBを通してデータを送ることができないのでPCMデータに偽装したDoP(DSD over PCM)という形式がある。DoPも送信元、送信先ともに対応している必要がある。

DSDのほうがアナログ感があるらしい。　

配信サービスについて

ハイレゾ音源のストリーミングと、ダウンロード可能なところとがある。

ストリーミング：TIDAL、Qobuz、Spotify、DEEZER、PrimeSeat、AppleMusic、

ダウンロード：e-onkyo music、mora、OTOTOY、Amazon Music HD
参考：http://www.alphapex.co.jp/deliver.html

再生環境について

再生ソフトウェア

デコーダーにライセンス料がかかるためMQA対応のフリーソフトはない。

MQA対応：Audirvana、Room など、MQSを FLAC コンテナにして再生することもできるがMQAとして再生するためにはMQAフルデコーダーのDACに出力する必要がある。正常にMQAで再生できればDACのMQAインジゲーターが光る。

FLAC：VOX、foobar2000、Amarra、HQ Player、MediaMonkey、Flacはオープンフォーマットだけあって再生対応アプリは多い。

iTunesから移行できそうなのは、MediaMonky、MusicBee などか

エンコーダー

FLACは公式版 https://ftp.osuosl.org/pub/xiph/releases/flac/、foobar2000、fre:ac、Exact Audio Copy

MQAのエンコーダーは一般にはなさそう

[TASK]CDデータの取り込みDBについて調査する

ハードウェア

ハイレゾはデジタルデータの問題でDACでアナログになった音声を出力するスピーカー、ヘッドフォンはそれなりのものであればハイレゾ対応でなくても問題はない。ハイレゾ対応であればより良い音が出るのはたしかだが、そこまでこだわる前にそれぞれのヘッドフォンやスピーカーの音の個性が好きかどうかを気にしたほうがいい。

ハイレゾ対応のポータブル再生機にはヘッドフォンの接続でバランス接続、アンバランス接続がある。アンバランスはRLでグランドが共通、アンバランスはRLでグランドが独立している。　アンバランスは既存の3.5mmジャック、バランス接続は4接点の2.5mm、5接点の4.4mmのジャック形状がある。

Bluetooth でハイレゾを再生機に送るなら、Bluetooth 5.0 以上で、aptX HD、AptX Adaptive、LDAC、HWA に対応している必要がある。