نام (NAME)

reuse-annotate - افزودن اطلاعات REUSE به فایل‌ها

خلاصه دستور (SYNOPSIS)

reuse annotate [گزینه‌ها] [فایل ...]

توضیحات (DESCRIPTION)

دستور reuse-annotate اطلاعات REUSE را به هدر فایل‌ها می‌افزاید. این قابلیت به‌ویژه در شرایطی سودمند است که بخواهید بدون نیاز به ویرایش دستی هدر تک‌تک فایل‌ها، دارنده حق نشر یا مجوز را به تعداد زیادی از فایل‌ها اضافه کنید.

هشدار:

هدر REUSE در بالاترین بخش فایل قرار می‌گیرد، به‌جز برخی هدرهای موجود مانند شِبانگ (#!) یا اعلان‌های XML (<?xml version="1.0"?>). اگر هدر متفاوتی حاوی اطلاعات حق نشر یا مجوز از قبل در فایل موجود باشد---در ابتدا یا هر جای دیگر---آن هدر به‌صورت درجا با اطلاعات REUSE ارائه‌شده جدید جایگزین می‌شود.

این ابزار تلاش می‌کند سبک کامنت‌گذاری مناسب را به‌طور خودکار از روی پسوند فایل تشخیص دهد و از همان سبک استفاده کند.

به‌طور معمول، ابزار در صورت در دسترس بودن از سبک کامنت تک‌خطی استفاده می‌کند (برای مثال، // به‌جای /* ... */ برای سبک‌های کامنت C++). اگر هیچ سبک کامنت تک‌خطی در دسترس نباشد، سبک چندخطی به کار می‌رود.

گزینه‌های اجباری (MANDATORY OPTIONS)

حداقل یکی (one) از گزینه‌های زیر الزامی است. این گزینه‌ها حاوی اطلاعاتی هستند که ابزار به فایل(ها) اضافه خواهد کرد. می‌توانید این گزینه‌ها را تکرار کنید.

سایر گزینه‌ها (OTHER OPTIONS)

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>

الگوها (TEMPLATES)

هنگامی که ابزار هدر را به یک فایل اضافه می‌کند، معمولاً ابتدا تمامی اعلان‌های حق نشر را به ترتیب حروف الفبا، متعاقباً همه مشارکت‌کنندگان را فهرست کرده، سپس یک خط خالی اضافه می‌کند و در نهایت تمامی عبارات مجوز SPDX را به ترتیب حروف الفبا می‌آورد. تغییر دادن این رفتار و استفاده از هدر سفارشی حاوی متن اضافی امکان‌پذیر است. این کار از طریق الگوهای Jinja2 انجام می‌شود.

الگوی پیش‌فرض عبارت است از:

{% 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 %}

الگوها بسته به سبک کامنت‌گذاریِ تشخیص داده شده یا مشخص شده، به‌طور خودکار توسط ابزار به صورت کامنت درمی‌آیند.

می‌توانید الگوهای Jinja2 اختصاصی خود را بسازید و آنها را در مسیر .reuse/templates/ قرار دهید. نام فایل الگوی شما باید حتماً به پسوند .jinja2 ختم شود.

درون الگو، به متغیرهای زیر دسترسی دارید:

در آینده ممکن است متغیرهای بیشتری اضافه شوند.

در برخی موارد، ممکن است بخواهید قالب‌بندی کامنت را به‌طور سفارشی انجام دهید. در این حالت‌ها می‌توانید هدر خود را از پیش به صورت کامنت قالب‌بندی کنید. هنگام انجام این کار، باید نام الگوی خود را به پسوند .commented.jinja2 ختم کنید.

نمونه‌ای از یک الگوی سفارشی با کامنت‌گذاری دستی:

/*
{% 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 "GPL-3.0-or-later" 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 %}
 */

مثال‌ها (EXAMPLES)

نحوه استفاده پایه به صورت reuse annotate --copyright="Jane Doe"; --license=MIT my_file.py است. این دستور هدر زیر را به فایل اضافه خواهد کرد (با فرض اینکه سال جاری ۲۰۱۹ باشد):

# SPDX-FileCopyrightText: 2019 Jane Doe
#
# SPDX-License-Identifier: MIT

نویسنده (AUTHOR)

Free Software Foundation Europe

حق نشر (COPYRIGHT)

2017, Free Software Foundation Europe. CC-BY-SA-4.0