C++语言学习(5): cppreference 介绍和离线文档

1. 绕不开的 cppreference

当你遇到不太熟悉的 C++ 语法，你大概率会去谷歌搜索，进而找到 cppreference.com 这个网站。

cppreference 并不是 C++ 标准委员会维护的，而是从2000年起，一群 C++ 爱好者发起和维护的， 通过网页上的广告提供盈利。 既然如此，为什么不直接看 C++ 标准委员会写的标准文档？

第一个原因：标准文档在 ISO 网站，要付费购买。

第二个原因：即使拿到了免费文档，例如 C++11 对应到 C++11 Working Draft N3337 - pdf （位于 open-std.org 网站），但是内容过于枯燥，大部分人不会“通过读字典来学习”。感受一下：
最终，我们来到了说人话的 cppreference.com 网站：

2. 获取 cppreference 离线文档

在线文档受制于网络，包括家里网络不好、网站被 rust 吹攻陷等情况，在本地下载查看离线文档是更好的方式。

页面 https://en.cppreference.com/w/Cppreference:Archives 给出了下载方式，

也可以自行从如下 git 仓库的 release 页面获取（它们都是从网站扒拉内容下来，原始内容其实是注册用户以 MediaWiki 形式编辑的）

• https://github.com/PeterFeicht/cppreference-doc（新，最近有维护）
• https://github.com/p12tic/cppreference-doc （原，5年没维护）

例如：
https://github.com/PeterFeicht/cppreference-doc/releases/tag/v20240610

本地解压后，打开 html-book-20240610/reference/en/index.html 即可查看离线文档：

3. 制作离线文档的 macOS app

上一步得到 html 文档可以直接用了，这一步则是把 html 文档的 index.html 作为应用程序，使得可以从 launchpad 快速启动文档。

为了在 launchpad 里显示图标，需要准备 .svg 图像并转为 png, 再转为 .icns:

brew install svg2png

获取 cpp.svg:
https://worldvectorlogo.com/logo/c

用脚本转为 icns:

#!/bin/bash
function svg_to_icns(){
    local RESOLUTIONS=(
        16,16x16
        32,16x16@2x
        32,32x32
        64,32x32@2x
        128,128x128
        256,128x128@2x
        256,256x256
        512,256x256@2x
        512,512x512
        1024,512x512@2x
    )

    for SVG in $@; do
      BASE=$(basename "$SVG" | sed 's/\.[^\.]*$//')
        ICONSET="$BASE.iconset"
        ICONSET_DIR="./icons/$ICONSET"
        mkdir -p "$ICONSET_DIR"
        for RES in ${RESOLUTIONS[@]}; do
            SIZE=$(echo $RES | cut -d, -f1)
            LABEL=$(echo $RES | cut -d, -f2)
            svg2png -w $SIZE -h $SIZE "$SVG" "$ICONSET_DIR"/icon_$LABEL.png
        done

        iconutil -c icns "$ICONSET_DIR"
    done
}

# download cpp.svg from https://worldvectorlogo.com/logo/c
function make_cpp_icns(){
    imagedir=~/Documents/cppreference/images
    cd $imagedir
    svg_to_icns cpp.svg
    cd -
}

make_cpp_icns

最后，是制作 App 的脚本，用到了刚刚做好的 .icns

#!/bin/bash

# This script generates /Application/Cppreference.app, which can be searched in launchpad
# You should have already downloaed cppreference HTML document from https://github.com/PeterFeicht/cppreference-doc/releases

mkdir -p ~/Applications/Cppreference.app/Contents/MacOS
mkdir -p ~/Applications/Cppreference.app/Contents/Resources

cat <<EOF > ~/Applications/Cppreference.app/Contents/MacOS/Cppreference
#!/bin/bash
open /Users/zz/Documents/cppreference/html-book-20240610/reference/en/index.html
EOF

chmod +x ~/Applications/Cppreference.app/Contents/MacOS/Cppreference


cat <<EOF > ~/Applications/Cppreference.app/Contents/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleExecutable</key>
    <string>Cppreference</string>
    <key>CFBundleIdentifier</key>
    <string>com.cppreference.en</string>
    <key>CFBundleName</key>
    <string>Cppreference</string>
    <key>CFBundleVersion</key>
    <string>20240610</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleIconFile</key>
    <string>cpp</string>
</dict>
</plist>
EOF

# download cpp.svg from https://worldvectorlogo.com/logo/c
cp ~/Documents/cppreference/images/icons/cpp.icns ~/Applications/Cppreference.app/Contents/Resources/

rm -rf /Applications/Cppreference.app
mv ~/Applications/Cppreference.app /Applications/

效果：

4. 总结

本文介绍了 cppreference 网站概况， 以及获取离线文档、制作为 macOS 应用程序的步骤，可用于日常 cpp 开发时加快文档的检索。