Squid Web Cache Wiki

Squid Web Cache 文档

🔗 man(8) 文档指南和标准

这是一份关于标准手册页文档格式和模板的指南。目的是让文档编写者专注于文档内容，而不是特定的格式和语义，并帮助自动化集成新文本与翻译字符串。

🔗 需要文档化的实体

安装在最终服务器系统上的所有应用程序二进制文件、脚本和配置文件都应通过手册页进行文档化。

🔗 文档格式

使用简化版的 ngroff 语法。有关 ngroff 格式的详细信息，请参阅 http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html。

为了与 po4a 翻译自动化集成，添加了一些额外的标记。有关特定标记和这些工具施加的限制的详细信息，请参阅 https://po4a.org/man/man3/Locale::Po4a::Man.3pm.php。

每个 .SH 段落前都应有一个空行。在 ngroff 语法中，这是一个只包含一个点的行（.），如下面 .TH 行和第一个 .SH 行之间的示例所示。

文档概述如下。按顺序是介绍性头部标记，然后是任何适用的章节。这些章节将在下面更详细地介绍。

.if !'po4a'hide' .TH binary.name 8
.
.SH NAME
.SH SYNOPSIS
.SH DESCRIPTION
.SH OPTIONS
.SH CONFIGURATION
.SH KNOWN ISSUES
.SH AUTHOR
.SH COPYRIGHT
.SH QUESTIONS
.SH REPORTING BUGS
.SH SEE ALSO

🔗 .SH NAME

一个初始内容行。

  1. 正在文档化的文件名。标记为非翻译内容。
  2. 一个连字符。标记为非翻译内容。
  3. 对文件的一行描述。适合用作标题。

如果版本号相关，请在名称详情下面的单独段落中说明。

例如

.
.SH NAME
squid \- HTTP Web Proxy caching server.
.PP
Version 1.0

文档

squid - HTTP Web Proxy caching server.

Version 1.0

🔗 .SH SYNOPSIS

纯命令行的选项语法。

如果选项带有参数，则这些参数描述符应保持开放以供翻译。语法的其他所有部分都应标记为非翻译内容。

例如

.
.SH SYNOPSIS
.if !'po4a'hide' .B squid
.if !'po4a'hide' .B [\-dh]
.if !'po4a'hide' .B [\-f
config\-file
.if !'po4a'hide' .B ]

文档

squid [-dh] [-f config-file ]

🔗 .SH DESCRIPTION

对文件对象内容的完整描述。它应该（但不要求）以粗体的文件名开头。描述中的段落通过 .PP 标签分隔。

使用 .if !‘po4a’hide’ 标记任何语法行为非翻译内容。

任何命名为文件或二进制文件的词都应以粗体标出。

例如

.
.SH DESCRIPTION
.PP
.B squid
is a high-performance proxy caching server for web clients,
supporting FTP, gopher, ICAP, ICP, HTCP and HTTP data objects.
Unlike traditional caching software,
Squid handles all requests in a single, non-blocking process.
.PP
Squid keeps meta data and especially hot objects cached in RAM,
caches DNS lookups, supports non-blocking DNS lookups, and implements
negative caching of failed requests.
.
.if !'po4a'hide' https://squid.org.cn/

🔗 .SH OPTIONS

一个完全文档化的可用命令行选项列表。每行之间有一个空行。描述文本的表格列偏移量为 12 个字符，在第一个 .TP 标记上设置。

选项开关和任何接受的变量名都应标记为非翻译内容（与 synopsis 不同）。

选项描述开放供翻译。变量名的任何重复都用粗体突出显示。

例如

.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-f config\-file"
Use configuration file
.B config\-file

🔗 .SH CONFIGURATION

特定于应用程序二进制文件和可能是辅助脚本的可选部分。

配置文件将在 .SH DESCRIPTION 下进行语法说明。

本节应包含配置片段。通常来自 squid.conf。实际的配置片段应标记为非翻译内容。

对于多行配置块，请使用 .br（小写很重要）来清晰地分割行。

:warning: 任何以连字符开头的词必须进行斜杠转义。

例如，URL 重写器会有类似这样的内容

.
.SH CONFIGURATION
.PP The simplest configuration for URL re-writers is to add the script or binary name to
.B squid.conf
like so:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B url_rewrite_program /usr/bin/squid/example.binary
.if !'po4a'hide' .RE
.PP Command line options sent to a helper script or binary are added to
.B squid.conf
following the helper binary name. Like so:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B url_rewrite_program /usr/bin/squid/example.binary \-d
.if !'po4a'hide' .br
.if !'po4a'hide' .B url_rewrite_access ...
.if !'po4a'hide' .RE

🔗 .SH KNOWN ISSUES

特定于应用程序二进制文件和可能是辅助脚本的可选部分。

由 .PP 段落组成的简单列表，概述了使用程序或脚本时已知的问

🔗 .SH AUTHOR

一个相关的段落列表，特定于所文档化程序、脚本或文件的作者风格。每个段落以作者姓名和联系方式列表结尾，并用 .PP 标签分隔。

对于与手册由同一人/多人编写的简单二进制文件或脚本

.
.SH AUTHOR
This program and documentation was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>

对于更复杂的情况，即应用程序有一个或多个作者，并且基于先前的工作

.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>
.if !'po4a'hide' .I Authors Name <author@email.contact>
.if !'po4a'hide' .I Authors Name <author@email.contact>
.PP
Based on prior work in
.B older.source
by
.if !'po4a'hide' .I Authors Name <author@email.contact>

其中手册文档由不同于程序的作者或作者编写

.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>
.PP
This manual was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>

与此二进制文件、脚本或配置文件相关的版权详情。

例如

.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
Squid
.B example.binary
and this manual is Copyright 2010
.if !'po4a'hide' .I Authors Name <author@email.contact>
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

如果不知道确切的版权详情，请使用以下片段

.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
This program and documentation is copyright to the authors named above.
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

🔗 .SH QUESTIONS

详细说明 Squid 项目用户帮助联系方式的逐字片段。

.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <squid-users@lists.squid-cache.org>

🔗 .SH REPORTING BUGS

应以标准文本开始，描述 Squid 项目的联系点。

.
.SH REPORTING BUGS
Bug reports need to be made in English.
See https://wiki.squid.org.cn/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <squid-bugs@lists.squid-cache.org>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <squid-dev@lists.squid-cache.org>

任何进一步的联系点或报告应列在 Squid 项目联系人之后，并以类似的语法编写。

🔗 .SH SEE ALSO

指向与此文件相关的其他文档的引用。

列出的每个项目都应占一行，以便于阅读，并允许单独标记为非翻译内容。

应首先列出其他手册页，然后列出描述的外部资源。

例如

.
.SH SEE ALSO
.if !'po4a'hide' .B squid "(8), "
.if !'po4a'hide' .B cachemgr.cgi "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' https://wiki.squid.org.cn/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' https://squid.org.cn/Doc/config/

🔗 模板

🔗 name.8 文件

这仅是一个模板。根据上述详细要求进行修改，以记录已安装的文件。

.if !'po4a'hide' .TH binary.name 8
.
.SH NAME
.if !'po4a'hide' binary.name
.if !'po4a'hide' \-
Description goes here
.PP
Version 1.0
.
.SH SYNOPSIS
.if !'po4a'hide' .B binary.name
.if !'po4a'hide' .B [\-dh]
.
.SH DESCRIPTION
.B binary.name
is an installed binary. The long description goes here
.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-h
Display the binary help and command line syntax info using stderr.
.
.SH KNOWN ISSUES
.PP
Optional test goes here. If there is nothing major remove the whole section.
.
.SH CONFIGURATION
.PP See FAQ wiki page for examples of how to write configuration snippets.
.PP Or just write what you want to say, then mark it up according to the wiki styles.
.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>
.if !'po4a'hide' .I Authors Name <author@email.contact>
.PP
Based on prior work in
.B older.source
by
.if !'po4a'hide' .I Authors Name <author@email.contact>
.PP
This manual was written by
.if !'po4a'hide' .I Authors Name <author@email.contact>
.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
This program and documentation is copyright to the authors named above.
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <squid-users@lists.squid-cache.org>
.
.SH REPORTING BUGS
Bug reports need to be made in English.
See https://wiki.squid.org.cn/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <squid-bugs@lists.squid-cache.org>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <squid-dev@lists.squid-cache.org>
.
.SH SEE ALSO
.if !'po4a'hide' .BR squid "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' https://wiki.squid.org.cn/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' https://squid.org.cn/Doc/config/

🔗 name.pl.in 文件

Perl 代码可以使用 pod2man 语法进行内联文档化，而不是单独的 .8 文件。

这仅是一个模板。根据上述详细要求进行修改，以记录已安装的文件。

 #!@PERL@

use strict;
use Pod::Usage;
use Getopt::Long;

=pod

=head1 NAME

binary.name - Brief Description goes here

Version 1.0

=head1 SYNOPSIS

 binary.name [options]

=head1 DESCRIPTION

 B<binary.name> is an installed binary. The long description goes here.

=head1 OPTIONS

=over 12

=item B<--debug>

Write debug info to stderr.

=item B<--help>

Display the binary help and command line syntax info using stderr.

=back

=head1 KNOWN ISSUES

Optional test goes here. If there is nothing major remove the whole section.

=head1 CONFIGURATION

See FAQ wiki page for examples of how to write configuration snippets.

Or just write what you want to say, then mark it up according to the wiki styles.

=head1 AUTHOR

This program was written by
I<Authors Name <author@email.contact>> ,
I<Authors Name <author@email.contact>>

Based on prior work in B<older.source> by I<Authors Name <author@email.contact>>

This manual was written by I<Authors Name <author@email.contact>>

=head1 COPYRIGHT

 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

=head1 QUESTIONS

Questions on the usage of this program can be sent to the I<Squid Users mailing list <squid-users@lists.squid-cache.org>>

=head1 REPORTING BUGS

Bug reports need to be made in English.
See https://wiki.squid.org.cn/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using http://bugs.squid-cache.org/

Report serious security bugs to I<Squid Bugs <squid-bugs@lists.squid-cache.org>>

Report ideas for new improvements to the I<Squid Developers mailing list <squid-dev@lists.squid-cache.org>>

=head1 SEE ALSO

squid (8), GPL (7),

The Squid FAQ wiki https://wiki.squid.org.cn/SquidFaq

The Squid Configuration Manual https://squid.org.cn/Doc/config/

=cut

# the script code follows

🔗 TODO

最佳实践是为服务器系统中安装的每个文件提供一个 man(x) 页。Squid 安装了许多各种类型的文件，如下表所示。目前正在努力将现有文本纳入匹配这些标准标记风格的工作。然而，有许多已安装的文件根本没有手册。

已安装文件 man(x) 当前状态
~/access.log :x: 缺少。相关？
~/cache.log :x: 缺少。相关？
~/netdb.state :x: 缺少。
~/store.log :x: 缺少。相关？
~/swap.state :x: 缺少。转换 wiki 页面信息
errors/errpages.css :x: 缺少
src/acl/external/delayer/ext_delayer_acl 8 :heavy_check_mark: 完成。
src/acl/external/AD_group/ext_ad_group_acl 8 :heavy_check_mark: 完成。
src/acl/external/file_userip/ext_file_userip_acl 8 :heavy_check_mark: 完成。
src/acl/external/kerberos_ldap_group/ext_kerberos_ldap_group_acl 8 :heavy_check_mark: 完成。
src/acl/external/LDAP_group/ext_ldap_group_acl 8 :heavy_check_mark: 完成。
src/acl/external/LM_group/ext_lm_group_acl 8 :heavy_check_mark: 完成。
src/acl/external/session/ext_session_acl 8 :heavy_check_mark: 完成。
src/acl/external/SQL_session/ext_sql_session_acl 8 :heavy_check_mark: 完成。
src/acl/external/unix_group/ext_unix_group_acl 8 :heavy_check_mark: 完成。
src/acl/external/wbinfo_group/ext_wbinfo_group_acl 8 :heavy_check_mark: 完成。
src/auth/basic/DB/basic_db_auth 8 :heavy_check_mark: 完成。
src/auth/basic/getpwnam/basic_getpwnam_auth 8 :heavy_check_mark: 完成。
src/auth/basic/LDAP/basic_ldap_auth 8 :heavy_check_mark: 完成。
src/auth/basic/NCSA/basic_ncsa_auth 8 :heavy_check_mark: 完成。
src/auth/basic/NIS/basic_nis_auth :x: 缺少。
src/auth/basic/PAM/basic_pam_auth 8 :heavy_check_mark: 完成。
src/auth/basic/POP3/basic_pop3_auth 8 :heavy_check_mark: 完成。
src/auth/basic/RADIUS/basic_radius_auth 8 :heavy_check_mark: 完成。
src/auth/basic/SASL/basic_sasl_auth 8 :heavy_check_mark: 完成。
src/auth/basic/SASL/basic_sasl_auth.pam :x: 缺少。
src/auth/basic/SASL/basic_sasl_auth.conf :x: 缺少。
src/auth/basic/SMB/basic_smb_auth :x: 缺少。
src/auth/basic/SMB/basic_smb_auth.sh :x: 缺少。
src/auth/basic/SMB_LM/basic_smb_lm_auth :x: 缺少。转换 README.html
src/auth/basic/SSPI/basic_sspi_auth.exe 8 :heavy_check_mark: 完成。
src/auth/digest/eDirectory/digest_edir_auth :x: 缺少。
src/auth/digest/LDAP/digest_ldap_auth :x: 缺少。
src/auth/digest/file/digest_file_auth 8 :heavy_check_mark: 完成。
src/auth/negotiate/kerberos/negotiate_kerberos_auth 8 :heavy_check_mark: 完成。
src/auth/negotiate/kerberos/negotiate_kerberos_auth_test :x: 缺少。转换 README
src/auth/negotiate/SSPI/negotiate_sspi_auth.exe 8 :heavy_check_mark: 完成。
src/auth/negotiate/wrapper/negotiate_wrapper :x: 缺少。
src/auth/ntlm/fake/ntlm_fake_auth :x: 缺少。转换 wiki NTLM fake auth 页面。
src/auth/ntlm/smb_lm/ntlm_smb_lm_auth :x: 缺少
src/auth/ntlm/SSPI/ntlm_sspi_auth.exe 8 :heavy_check_mark: 完成。
src/DiskIO/DiskDaemon/diskd :x: 缺少
src/http/url_rewriters/fake/url_fake_rewrite :x: 缺少
src/http/url_rewriters/fake/url_fake_rewrite.sh :x: 缺少
src/http/url_rewriters/LFS/url_lfs_rewrite 8 :heavy_check_mark: 完成。
src/icmp/pinger :x: 缺少
src/log/file/log_file_daemon :x: 缺少。
src/log/DB/log_db_daemon 8 :heavy_check_mark: 完成。
src/mime.conf :x: 缺少
src/mime.conf.default :x: 缺少。链接到 mime.conf 手册？
src/recv-announce :x: 缺少。
src/security/cert_generators/file/security_file_certgen 8 :heavy_check_mark: 完成。
src/security/cert_validators/fake/security_fake_certverify 8 :heavy_check_mark: 完成。
src/squid 8 :heavy_check_mark: 完成。
src/squid.conf :x: 缺少。转换 squid.conf.documented
src/squid.conf.default 不适用 使用 https://squid.org.cn/Doc/config/ 代替
src/squid.conf.documented 不适用 使用 https://squid.org.cn/Doc/config/ 代替
src/store/id_rewriters/file/storeid_file_rewrite 8 :heavy_check_mark: 完成。
src/unlinkd :x: 缺少
tools/cachemgr.cgi 8 :heavy_check_mark: 完成。
tools/helper-mux.pl 8 :worried: 需要审查 perl/pod 输出。
tools/purge/ 1 :heavy_check_mark: 完成。
tools/squidclient/ 1 :heavy_check_mark: 完成。
导航：网站搜索，网站页面，分类，🔼 向上