.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.3 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "REUSE-ANNOTATE" "1" "Dec 17, 2025" "6.2.0" "reuse"
.SH "نام (NAME)"
reuse-annotate \- افزودن اطلاعات REUSE به فایل‌ها
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBreuse annotate\fP [\fIگزینه‌ها\fP] [\fIفایل\fP ...]
.SH "توضیحات (DESCRIPTION)"
.sp
دستور \fBreuse\-annotate\fP اطلاعات REUSE را به هدر فایل‌ها می‌افزاید. این قابلیت به‌ویژه در شرایطی سودمند است که بخواهید بدون نیاز به ویرایش دستی هدر تک‌تک فایل‌ها، دارنده حق نشر یا مجوز را به تعداد زیادی از فایل‌ها اضافه کنید.
.sp
\fBهشدار:\fP
.INDENT 0.0
.INDENT 3.5
باید هنگام استفاده از \fBannotate\fP در فرآیندهای خودکار محتاط باشید. هرچند چیزی مانع استفاده از آن در اسکریپت‌های انتشار شما نمی‌شود، اما باید اطمینان حاصل کنید اطلاعاتی که اضافه می‌کند واقعاً بازتاب‌دهنده واقعیت باشد. بهتر است این موضوع به‌صورت دستی بررسی و اعتبارسنجی شود.
.UNINDENT
.UNINDENT
.sp
هدر REUSE در بالاترین بخش فایل قرار می‌گیرد، به‌جز برخی هدرهای موجود مانند شِبانگ (\fB#!\fP) یا اعلان‌های XML (\fB<?xml version=\(dq1.0\(dq?>\fP). اگر هدر متفاوتی حاوی اطلاعات حق نشر یا مجوز از قبل در فایل موجود باشد\-\-\-در ابتدا یا هر جای دیگر\-\-\-آن هدر به‌صورت درجا با اطلاعات REUSE ارائه‌شده جدید جایگزین می‌شود.
.sp
این ابزار تلاش می‌کند سبک کامنت‌گذاری مناسب را به‌طور خودکار از روی پسوند فایل تشخیص دهد و از همان سبک استفاده کند.
.sp
به‌طور معمول، ابزار در صورت در دسترس بودن از سبک کامنت تک‌خطی استفاده می‌کند (برای مثال، \fB//\fP به‌جای \fB/* ... */\fP برای سبک‌های کامنت C++). اگر هیچ سبک کامنت تک‌خطی در دسترس نباشد، سبک چندخطی به کار می‌رود.
.SH "گزینه‌های اجباری (MANDATORY OPTIONS)"
.sp
حداقل یکی (\fIone\fP) از گزینه‌های زیر الزامی است. این گزینه‌ها حاوی اطلاعاتی هستند که ابزار به فایل(ها) اضافه خواهد کرد. می‌توانید این گزینه‌ها را تکرار کنید.
.INDENT 0.0
.TP
.B \-c, \-\-copyright COPYRIGHT
دارنده حق نشر. این مقدار شامل سال یا پیشوند حق نشر نیست. برای سال و پیشوند، گزینه‌های \fB\-\-year\fP و \fB\-\-copyright\-prefix\fP را ببینید.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-license LICENSE
شناسه مجوز SPDX.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-contributor CONTRIBUTOR
نام مشارکت‌کننده. مشارکت‌کننده از طریق برچسب \fBSPDX\-FileContributor:\fP اضافه خواهد شد.
.UNINDENT
.SH "سایر گزینه‌ها (OTHER OPTIONS)"
.INDENT 0.0
.TP
.B \-y, \-\-year YEAR
تعیین سال اعلان(های) حق نشر. اگر مشخص نشود، سال به صورت پیش‌فرض برابر با سال جاری خواهد بود. مقدار می‌تواند یک بازه (پیچیده) باشد، مانند \(aq2017\-2019\(aq یا \(aq2017, 2019\-2022, 2024\-Present\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-style STYLE
لغو سازوکار تشخیص خودکار سبک کامنت برای تحمیل یک سبک کامنت مشخص به فایل‌ها. این گزینه زمانی کاربرد دارد که پسوند فایل شناخته‌شده نباشد، یا به سبک کامنتی مرتبط شده باشد که با آن موافق نیستید.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-copyright\-prefix PREFIX
پیشوندی که باید در اعلان حق نشر استفاده شود. اگر تعیین نشود، به‌صورت پیش‌فرض از \fBspdx\fP به عنوان پیشوند استفاده می‌شود. پیشوندهای حق نشر موجود عبارتند از:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
spdx:               SPDX\-FileCopyrightText: <year> <author>
spdx\-c:             SPDX\-FileCopyrightText: (C) <year> <author>
spdx\-symbol:        SPDX\-FileCopyrightText: © <year> <author>
spdx\-string:        SPDX\-FileCopyrightText: Copyright <year> <author>
spdx\-string\-c:      SPDX\-FileCopyrightText: Copyright (C) <year> <author>
spdx\-string\-symbol: SPDX\-FileCopyrightText: Copyright © <year> <author>
string:             Copyright <year> <author>
string\-c:           Copyright (C) <year> <author>
string\-symbol:      Copyright © <year> <author>
symbol:             © <year> <author>
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-template TEMPLATE
الگوی مورد استفاده برای هدر کامنت. نام الگو با نام فایل الگو در مسیر \fB\&.reuse/templates/\fP بدون پسوند \fB\&.jinja2\fP یا \fB\&.commented.jinja2\fP مطابقت دارد.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-exclude\-year
سال را در اعلان حق نشر نگنجان.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-merge\-copyrights
اگر دو (یا چند) اعلان حق نشر به جز در سال‌ها یکسان باشند، آنها را به صورت یک خط واحد با سال‌های ترکیب‌شده خروجی بده.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-single\-line
اجبار ابزار به استفاده از سبک کامنت‌گذاری تک‌خطی. برای C، این معادل \fB//\fP خواهد بود.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-multi\-line
اجبار ابزار به استفاده از سبک کامنت‌گذاری چندخطی. برای C، این معادل \fB/* ... */\fP خواهد بود.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-recursive
افزودن اطلاعات به همه فایل‌ها به صورت بازگشتی در مسیر مشخص‌شده.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-replace
به جای جایگزینی اولین هدر موجود در فایل که حاوی اطلاعات حق نشر و مجوز است، آن را نگه دار و یک هدر جدید در بالای فایل ایجاد کن.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force\-dot\-license
همیشه به جای تلاش برای نوشتن در خود فایل، یک فایل .license بنویس.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-fallback\-dot\-license
به جای متوقف کردن عملیات هنگامی که پسوند فایل سبک کامنت‌گذاری مرتبطی ندارد، برای آن فایل‌ها یک فایل .license ایجاد کن.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-skip\-unrecognised
به جای متوقف کردن عملیات هنگامی که پسوند فایل سبک کامنت‌گذاری مرتبطی ندارد، از آن فایل‌ها صرف‌نظر کن.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help
نمایش راهنما و خروج.
.UNINDENT
.SH "الگوها (TEMPLATES)"
.sp
هنگامی که ابزار هدر را به یک فایل اضافه می‌کند، معمولاً ابتدا تمامی اعلان‌های حق نشر را به ترتیب حروف الفبا، متعاقباً همه مشارکت‌کنندگان را فهرست کرده، سپس یک خط خالی اضافه می‌کند و در نهایت تمامی عبارات مجوز SPDX را به ترتیب حروف الفبا می‌آورد. تغییر دادن این رفتار و استفاده از هدر سفارشی حاوی متن اضافی امکان‌پذیر است. این کار از طریق الگوهای Jinja2 انجام می‌شود.
.sp
الگوی پیش‌فرض عبارت است از:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% for copyright_line in copyright_lines %}
{{ copyright_line }}
{% endfor %}
{% for contributor_line in contributor_lines %}
SPDX\-FileContributor: {{ contributor_line }}
{% endfor %}

{% for expression in spdx_expressions %}
SPDX\-License\-Identifier: {{ expression }}
{% endfor %}
.EE
.UNINDENT
.UNINDENT
.sp
الگوها بسته به سبک کامنت‌گذاریِ تشخیص داده شده یا مشخص شده، به‌طور خودکار توسط ابزار به صورت کامنت درمی‌آیند.
.sp
می‌توانید الگوهای Jinja2 اختصاصی خود را بسازید و آنها را در مسیر \fB\&.reuse/templates/\fP قرار دهید. نام فایل الگوی شما باید حتماً به پسوند \fB\&.jinja2\fP ختم شود.
.sp
درون الگو، به متغیرهای زیر دسترسی دارید:
.INDENT 0.0
.IP \(bu 2
\fBcopyright_lines\fP \-\-\- فهرستی از اعلان‌های حق نشر (رشته).
.IP \(bu 2
\fBcontributor_lines\fP \-\-\- فهرستی از مشارکت‌کنندگان (رشته).
.IP \(bu 2
\fBspdx_expressions\fP \-\-\- فهرستی از عبارات مجوز SPDX (رشته).
.UNINDENT
.sp
در آینده ممکن است متغیرهای بیشتری اضافه شوند.
.sp
در برخی موارد، ممکن است بخواهید قالب‌بندی کامنت را به‌طور سفارشی انجام دهید. در این حالت‌ها می‌توانید هدر خود را از پیش به صورت کامنت قالب‌بندی کنید. هنگام انجام این کار، باید نام الگوی خود را به پسوند \fB\&.commented.jinja2\fP ختم کنید.
.sp
نمونه‌ای از یک الگوی سفارشی با کامنت‌گذاری دستی:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/*
{% for copyright_line in copyright_lines %}
 * {{ copyright_line }}
{% endfor %}
{% if copyright_lines and spdx_expressions %}
 *
{% endif %}
{% for expression in spdx_expressions %}
 * SPDX\-License\-Identifier: {{ expression }}
{% endfor %}
{% if \(dqGPL\-3.0\-or\-later\(dq in spdx_expressions %}
 *
 * This program is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later
 * version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <https://www.gnu.org/licenses>.
{% endif %}
 */
.EE
.UNINDENT
.UNINDENT
.SH "مثال‌ها (EXAMPLES)"
.sp
نحوه استفاده پایه به صورت \fBreuse annotate \-\-copyright=\(dqJane Doe\(dq \-\-license=MIT my_file.py\fP است. این دستور هدر زیر را به فایل اضافه خواهد کرد (با فرض اینکه سال جاری ۲۰۱۹ باشد):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# SPDX\-FileCopyrightText: 2019 Jane Doe
#
# SPDX\-License\-Identifier: MIT
.EE
.UNINDENT
.UNINDENT
.SH "نویسنده (AUTHOR)"
Free Software Foundation Europe
.SH "حق نشر (COPYRIGHT)"
2017, Free Software Foundation Europe. CC-BY-SA-4.0
.\" End of generated man page.