.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "dpkg-parsechangelog 1"
.TH dpkg-parsechangelog 1 2026-03-06 1.23.7-dirty "dpkg suite"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
dpkg\-parsechangelog \- تجزیه و نمایش فایل‌های تغییرات دبیان (changelog)
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
\&\fBdpkg\-parsechangelog\fR
[\fIگزینه\fR...]
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
دستور
\&\fBdpkg\-parsechangelog\fR
فایل تغییرات (changelog) یک درخت سورس استخراج‌شدهٔ دبیان را خوانده و تجزیه می‌کند و اطلاعات درون آن را در یک قالب ماشین‌خوان به خروجی استاندارد می‌فرستد.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
.IP "\fB\-l\fR, \fB\-\-file\fR \fIchangelog\-file\fR" 4
.IX Item "-l, --file changelog-file"
فایل تغییراتی را که اطلاعات باید از آن خوانده شود مشخص می‌کند.
می‌توان از \(oq\-\(cq برای مشخص کردن خواندن از ورودی استاندارد استفاده کرد.
مقدار پیش‌فرض
\&\fBdebian/changelog\fR
است.
.IP "\fB\-F\fR \fIchangelog\-format\fR" 4
.IX Item "-F changelog-format"
قالب فایل تغییرات را مشخص می‌کند.
به‌طور پیش‌فرض، قالب از یک خط ویژه در نزدیکی انتهای فایل تغییرات خوانده می‌شود، یا در صورت نبود آن، به قالب استاندارد
\fBdebian\fR
تنظیم می‌شود.
همچنین بخش «قالب‌های فایل تغییرات (CHANGELOG FORMATS)» را ببینید.
.IP "\fB\-L\fR \fIlibdir\fR" 4
.IX Item "-L libdir"
گزینهٔ منسوخ‌شده و بدون اثر (از نسخه 1.18.8 بسته dpkg به بعد).
تنظیم متغیرهای محیطی پرل
\fBPERL5LIB\fR
یا
\fBPERLLIB\fR
هنگام جستجو برای ماژول‌های پرلِ تجزیه‌کننده اثر مشابهی دارد.
.IP "\fB\-S\fR, \fB\-\-show\-field\fR \fIfield\fR" 4
.IX Item "-S, --show-field field"
نام فیلدی که باید نمایش داده شود را مشخص می‌کند (از نسخه 1.17.0 بسته dpkg به بعد).
نام فیلد چاپ نمی‌شود، بلکه فقط مقدار آن نمایش می‌یابد.
.IP "\fB\-?\fR, \fB\-\-help\fR" 4
.IX Item "-?, --help"
نمایش پیام راهنما و خروج.
.IP \fB\-\-version\fR 4
.IX Item "--version"
نمایش نسخه و خروج.
.SS "گزینه‌های تجزیه‌کننده (Parser Options)"
.IX Subsection "Parser Options"
از گزینه‌های زیر می‌توان برای اثرگذاری بر خروجی تجزیه‌کنندهٔ فایل تغییرات استفاده کرد؛ برای نمونه محدودهٔ مدخل‌ها یا قالب خروجی.
.IP "\fB\-\-format\fR \fIoutput\-format\fR" 4
.IX Item "--format output-format"
قالب خروجی را تعیین می‌کند.
مقادیر پشتیبانی‌شده در حال حاضر
\&\fBdpkg\fR
و
\fBrfc822\fR
هستند.
\&\fBdpkg\fR
قالب خروجی کلاسیک (پیش از ارائهٔ این گزینه) و مقدار پیش‌فرض است.
این قالب شامل یک بند در قالب کنترل دبیان است (ببینید \fBdeb\-control\fR\|(5)).
اگر بیش از یک مدخل درخواست شود، بیشتر فیلدها از نخستین مدخل (معمولاً جدیدترین مدخل) گرفته می‌شوند، مگر آن‌که خلاف آن بیان شده باشد:
.RS 4
.IP "\fBSource:\fR \fIpkg\-name\fR" 4
.IX Item "Source: pkg-name"
نام بستهٔ سورس.
.IP "\fBVersion:\fR \fIversion\fR" 4
.IX Item "Version: version"
شماره نسخهٔ سورس.
\&\fBتوجه\fR: برای انتشار‌های فقط باینری ممکن است انتشار سورس متناظری وجود نداشته باشد.
.IP "\fBDistribution:\fR \fItarget\-distribution\fR" 4
.IX Item "Distribution: target-distribution"
فهرستی جداشده با فاصله از یک یا چند نام توزیع که این نسخه هنگام بارگذاری باید در آن‌ها نصب شود.
.IP "\fBUrgency:\fR \fIurgency\fR" 4
.IX Item "Urgency: urgency"
بالاترین فوریت در میان تمام مدخل‌های گنجانده‌شده استفاده می‌شود، که در ادامهٔ آن توضیحات تمام نسخه‌های درخواستی (جداشده با فاصله) قرار می‌گیرد.
.IP "\fBMaintainer:\fR \fIauthor\fR" 4
.IX Item "Maintainer: author"
نام و نشانی ایمیل فردی که این تغییرات را آماده کرده است؛ این اطلاعات \fBلزوماً\fR متعلق به بارگذار (uploader) یا نگه‌دارندهٔ معمول بسته نیست.
.IP "\fBDate:\fR \fIdate\fR" 4
.IX Item "Date: date"
تاریخ مدخل به صورت یک رشته، همان‌گونه که در فایل تغییرات درج شده است.
با قالب \fBstrptime\fR\|(3) به صورت "\fR\f(CB%a\fR\fB, \fR\f(CB%d\fR\fB \fR\f(CB%b\fR\fB \fR\f(CB%Y\fR\fB \fR\f(CB%T\fR\fB \fR\f(CB%z\fR\fB\fR"، با این حال ممکن است روز هفته با روز واقعی به‌دست‌آمده از ادامهٔ رشتهٔ تاریخ تطابق نداشته باشد.
اگر به نمایش دقیق‌تری از تاریخ نیاز دارید، از فیلد
\&\fBTimestamp\fR
استفاده کنید، اما در نظر داشته باشید که ممکن است نتوان آن را مجدداً به مقدار دقیق موجود در این فیلد نگاشت کرد.
.IP "\fBTimestamp:\fR \fItimestamp\fR" 4
.IX Item "Timestamp: timestamp"
تاریخ مدخل به صورت یک برچسب زمانی بر حسب ثانیه از مبدأ یونیکس (epoch) (از نسخه 1.18.8 بسته dpkg به بعد).
.IP "\fBCloses:\fR \fIbug\-number\fR" 4
.IX Item "Closes: bug-number"
فیلدهای Closes تمام مدخل‌های گنجانده‌شده با یکدیگر ادغام می‌شوند.
.IP "\fBChanges:\fR \fIchangelog\-entries\fR" 4
.IX Item "Changes: changelog-entries"
متن تمام مدخل‌های تغییرات به یکدیگر پیوند داده می‌شوند.
برای اینکه این فیلد به یک فیلد چندخطی معتبر در قالب کنترل دبیان تبدیل شود، خطوط خالی با یک نقطهٔ تنها جایگزین شده و در ابتدای تمام خطوط یک نویسهٔ فاصله قرار می‌گیرد.
محتوای دقیق به قالب changelog بستگی دارد.
.RE
.RS 4
.Sp
فیلدهای \fBVersion\fR، \fBDistribution\fR، \fBUrgency\fR، \fBMaintainer\fR و
\&\fBChanges\fR
اجباری هستند.
.Sp
ممکن است فیلدهای اضافیِ تعریف‌شده توسط کاربر نیز وجود داشته باشند.
.Sp
قالب \fBrfc822\fR از فیلدهای مشابهی استفاده می‌کند اما برای هر مدخل تغییرات یک بند جداگانه نمایش می‌دهد تا تمامی متاداده‌های هر مدخل حفظ شوند.
.RE
.IP \fB\-\-reverse\fR 4
.IX Item "--reverse"
گنجاندن تمام تغییرات با ترتیب معکوس (از نسخه 1.19.1 بسته dpkg به بعد).
.Sp
\&\fBتوجه\fR: برای قالب \fBdpkg\fR نخستین مدخل، قدیمی‌ترین مدخل خواهد بود.
.IP \fB\-\-all\fR 4
.IX Item "--all"
گنجاندن تمام تغییرات.
\&\fBتوجه\fR: هنگام استفاده از این گزینه، سایر گزینه‌ها هیچ اثری نخواهند داشت.
.IP "\fB\-s\fR, \fB\-\-since\fR \fIversion\fR" 4
.IX Item "-s, --since version"
.PD 0
.IP "\fB\-v\fR \fIversion\fR" 4
.IX Item "-v version"
.PD
گنجاندن تمام تغییرات جدیدتر از \fIversion\fR.
.IP "\fB\-u\fR, \fB\-\-until\fR \fIversion\fR" 4
.IX Item "-u, --until version"
گنجاندن تمام تغییرات قدیمی‌تر از \fIversion\fR.
.IP "\fB\-f\fR, \fB\-\-from\fR \fIversion\fR" 4
.IX Item "-f, --from version"
گنجاندن تمام تغییرات مساوی یا جدیدتر از \fIversion\fR.
.IP "\fB\-t\fR, \fB\-\-to\fR \fIversion\fR" 4
.IX Item "-t, --to version"
گنجاندن تمام تغییرات تا یا مساوی \fIversion\fR.
.IP "\fB\-c\fR, \fB\-\-count\fR \fInumber\fR" 4
.IX Item "-c, --count number"
.PD 0
.IP "\fB\-n\fR \fInumber\fR" 4
.IX Item "-n number"
.PD
گنجاندن \fInumber\fR مدخل از بالا (یا از انتها در صورتی که \fInumber\fR کمتر از 0 باشد).
.IP "\fB\-o\fR, \fB\-\-offset\fR \fInumber\fR" 4
.IX Item "-o, --offset number"
تغییر نقطهٔ شروع برای گزینهٔ \fB\-\-count\fR، شمارش‌شده از بالا (یا از انتها در صورتی که \fInumber\fR کمتر از 0 باشد).
.SH "قالب‌های فایل تغییرات (CHANGELOG FORMATS)"
.IX Header "CHANGELOG FORMATS"
استفاده از قالبی متفاوت با قالب استاندارد امکان‌پذیر است، به شرط آن‌که یک تجزیه‌کننده برای آن قالب جایگزین ارائه شود.
.PP
برای اینکه \fBdpkg\-parsechangelog\fR تجزیه‌کنندهٔ جدید را اجرا کند، باید خطی در میان ۴۰ خط پایانی فایل تغییرات گنجانده شود که با عبارت منظم پرل زیر مطابقت داشته باشد:
\(lq\fB\eschangelog\-format:\es+([0\-9a\-z]+)\eW\fR\(rq.
بخش درون پرانتز باید نام قالب باشد.
برای نمونه:
.Sp
.RS 4
@@@ changelog\-format: \fIotherformat\fR @@@
.RE
.PP
نام‌های قالب فایل تغییرات رشته‌هایی غیرخالی متشکل از نویسه‌های الفبارقمی کوچک (\(lqa\-z0\-9\(rq) هستند.
.PP
اگر چنین خطی وجود داشته باشد، آنگاه \fBdpkg\-parsechangelog\fR به دنبال تجزیه‌کننده در قالب ماژول پرل
\fBDpkg::Changelog::\fR\fIOtherformat\fR
خواهد گشت؛ و در صورت عدم وجود آن، با خطا متوقف خواهد شد.
نام تجزیه‌کننده در ماژول پرل به طور خودکار با حرف اول بزرگ نوشته می‌شود.
قالب پیش‌فرض فایل تغییرات \fBdebian\fR است و یک تجزیه‌کننده برای آن به طور پیش‌فرض ارائه شده است.
.PP
تجزیه‌کننده باید از کلاس Dpkg::Changelog مشتق شده باشد و رابط کاربری مستندسازی‌شده و مورد نیاز را پیاده‌سازی کند.
.PP
اگر قالب فایل تغییراتی که تجزیه می‌شود همیشه یا تقریباً همیشه یک خط خالی بین یادداشت‌های تغییرات جداگانه باقی می‌گذارد، این خطوط خالی باید حذف شوند تا خروجی نهایی فشرده باشد.
.PP
اگر قالب فایل تغییرات فاقد اطلاعات تاریخ یا نام بسته باشد، این اطلاعات باید از خروجی حذف شوند.
تجزیه‌کننده نباید تلاش کند آن‌ها را تولید کرده یا از منابع دیگر بیابد.
.PP
اگر فایل تغییرات قالب مورد انتظار را نداشته باشد، تجزیه‌کننده باید با خطا خارج شود، به جای اینکه سعی کند به کار ادامه دهد و احتمالاً خروجی نادرست تولید نماید.
.PP
یک تجزیه‌کنندهٔ فایل تغییرات به هیچ وجه نباید با کاربر تعامل داشته باشد.
.SH "نکات (NOTES)"
.IX Header "NOTES"
تمام \fBگزینه‌های تجزیه‌کننده\fR به جز \fB\-v\fR تنها از نسخه 1.14.16 بسته dpkg به بعد پشتیبانی می‌شوند.
.PP
تجزیه گزینه‌های کوتاه با مقادیر تفکیک‌نشده تنها از نسخه 1.18.0 بسته dpkg به بعد در دسترس است.
.SH "محیط (ENVIRONMENT)"
.IX Header "ENVIRONMENT"
.IP \fBDPKG_COLORS\fR 4
.IX Item "DPKG_COLORS"
حالت رنگ را تنظیم می‌کند (از نسخه 1.18.5 بسته dpkg به بعد).
مقادیر پذیرفته‌شدهٔ کنونی عبارتند از: \fBauto\fR (پیش‌فرض)، \fBalways\fR و
\&\fBnever\fR.
.IP \fBDPKG_NLS\fR 4
.IX Item "DPKG_NLS"
در صورت تنظیم، برای تصمیم‌گیری در خصوص فعال‌سازی پشتیبانی از زبان مادری (Native Language Support)، که به عنوان پشتیبانی از بومی‌سازی یا بین‌المللی‌سازی (i18n) نیز شناخته می‌شود، به کار می‌رود (از نسخه 1.19.0 بسته dpkg به بعد).
مقادیر پذیرفته‌شده عبارتند از: \fB0\fR و \fB1\fR (پیش‌فرض).
.SH "فایل‌ها (FILES)"
.IX Header "FILES"
.IP \fBdebian/changelog\fR 4
.IX Item "debian/changelog"
فایل تغییرات، که برای دریافت اطلاعات وابسته به نسخه دربارهٔ بستهٔ سورس به کار می‌رود؛ از جمله فوریت و توزیع یک بارگذاری، تغییرات انجام‌شده پس از یک انتشار خاص، و خود شماره نسخهٔ سورس.
.SH "اشکالات (BUGS)"
.IX Header "BUGS"
فیلد \fBMaintainer\fR نام گیج‌کننده‌ای دارد که با فیلد موجود در فایل
\fIdebian/control\fR
هم‌نام است اما با معنای دقیق آن یکسان نیست؛ در حالی که مفهوم آن با نام فیلد
\fBChanged\-By\fR
که در فایل \fI.changes\fR استفاده می‌شود، بهتر بیان می‌شد.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBdeb\-changelog\fR\|(5).