TEXPROFILE(1) نمایش پروفایل‌های TeX TEXPROFILE(1)

texprofile - نمایش داده‌های پروفایل جمع‌آوری‌شده توسط texprof.

texprofile [گزینه‌ها] inputfile

texprofile فایل دودویی inputfile تولیدشده توسط texprof را می‌خواند. پسوند .tprof فایل ورودی می‌تواند نادیده گرفته شود. این برنامه داده‌ها را تحلیل کرده و نتایج را در قالب جدول‌های گوناگون ارائه می‌دهد، که یا برای خوانایی انسان بهینه‌سازی شده‌اند یا به عنوان فایل‌های CSV (مقادیر جداشده با کاما) جهت پردازش‌های بعدی هستند.

خروجی در جریان خروجی استاندارد نوشته می‌شود که می‌توان آن را به یک فایل هدایت کرد یا بلافاصله مشاهده نمود.

چهار نوع گزینه وجود دارد: گزینه‌های عمومی، گزینه‌های جدول، گزینه‌های انتخاب، و گزینه‌های قالب‌بندی.

گزینه‌های عمومی:

-? -h --help
نمایش یک متن راهنمای کوتاه و خروج از برنامه.
نمایش اطلاعات نسخه و خروج.

گزینه‌های جدول مشخص می‌کنند که کدام جدول‌ها نمایش داده خواهند شد. این گزینه‌ها همگی از حروف بزرگ استفاده می‌کنند. اگر هیچ گزینهٔ جدولی مشخص نشود، تنها برخی اطلاعات سراسری نمایش داده می‌شود.

نمایش جدول ۱۰ خط ورودی برتر.
نمایش جدول گراف فراخوانی ماکرو.
نمایش جدول زمان‌ها به ازای هر دستور TeX.
نمایش جدول زمان‌ها به ازای هر خط ورودی.
نمایش جدول برچسب‌های زمانی خام.
نمایش جدول تغییرات پشتهٔ ماکرو.
نمایش جدول تمام فایل‌های ورودی.
نمایش جدول تمام ماکروهای فراخوانی‌شده.
نمایش جدول‌های مهم (معادل جدول‌های -TGFC).
عدم نمایش جدول اطلاعات سراسری.

گزینه‌های انتخاب امکان کاهش حجم داده‌های نمایش‌یافته در جدول را با حذف مدخل‌هایی که سهم اندکی در زمان اجرای کلی دارند، فراهم می‌کنند.

عدم نمایش اطلاعات برای مدخل‌های جدول با زمان تجمعی کمتر از n درصد. مقدار پیش‌فرض ۱.۰ درصد است.
محدود کردن تعداد خطوط ورودی نمایش‌داده‌شده در جدول «۱۰ خط برتر» به n. این گزینه تنها همراه با گزینهٔ -T کاربرد دارد.

گزینه‌های قالب‌بندی، نحوهٔ قالب‌بندی اطلاعات در جدول‌ها و همچنین انتخاب اطلاعاتی را که در جدول‌ها نشان داده می‌شوند، تعیین می‌کنند.

افزودن نام فایل و شماره خطوط ماکروها پس از نام ماکرو. این گزینه برای تمایز قائل شدن میان دو ماکرو که نام یکسانی دارند مفید است.
بهینه‌سازی خروجی برای خوانایی ماشین. هنگام بهینه‌سازی برای خوانایی انسان، زمان‌ها گرد شده و به شکل کوتاه با افزودن شناسهٔ یکا نمایش داده می‌شوند: s برای ثانیه، ms برای میلی‌ثانیه، us برای میکروثانیه، و ns برای نانوثانیه. این قالب در صورتی که بخواهید داده‌ها را برای نمونه جهت پردازش بیشتر به یک صفحه‌گسترده (spread-sheet) وارد کنید، نامناسب است. با گزینهٔ -m زمان‌ها صرفاً بر حسب نانوثانیه و بدون یکا ارائه می‌شوند. مشابه این مورد، زمان ترکیبی برای کل زمان صرف‌شده جهت یک ماکرو و زمان استفاده‌شده به عنوان زیرماکرو از گراف فراخوانی، در یک ستون با خط مورب برای جداسازی هر دو عدد نمایش داده می‌شود که برای خوانندگان انسان مناسب است. با گزینهٔ -m هر دو عدد صرفاً در ستون‌های جداگانه ارائه خواهند شد.
نمایش شماره‌های برچسب زمانی. این گزینه در صورتی که جدول را وارد یک پایگاه‌داده یا صفحه‌گسترده کنید، همراه با گزینهٔ -R مفید است. اگر داده‌ها را بر پایهٔ ویژگی‌های گوناگون در دسته‌های مختلف مرتب کنید، از شماره برچسب زمانی می‌توان برای نگه‌داشتن مدخل‌های درون یک دسته به صورت مرتب‌شده بر اساس زمان استفاده کرد.
نمایش تغییرات پشتهٔ ماکرو. این گزینه همراه با گزینهٔ -R کاربرد دارد در صورتی که بخواهید تغییرات پشتهٔ ماکرو (ببینید -S) را همراه با اطلاعات زمان‌بندی در یک جدول واحد مشاهده کنید.

هنگامی که texprof در حال اجرا است، به هر فایل ورودی TeX یک شمارهٔ فایل یکتا اختصاص داده می‌شود. نام فایل به‌تنهایی اغلب یکتا نیست چرا که ممکن است دو فایل در دایرکتوری‌های مختلف دارای نام یکسانی باشند. با این حال، نمایش نام کامل فایل به همراه مسیر کامل آن اغلب چندان راحت نیست. بنابراین اگر نام فایل یکسانی را همراه با شماره‌های فایل متفاوتی مشاهده کردید، می‌توانید از گزینهٔ -F برای دریافت جدولی از تمام شماره‌های فایل و نام‌های کامل آن‌ها استفاده کنید.

اما حتی درون یک دایرکتوری یکسان، TeX می‌تواند فایل‌های متفاوتی با نام یکسان را در طول یک اجرا بخواند: TeX می‌تواند فایلی را برای نوشتن باز کند، محتوا را در آن بنویسد، آن را ببندد، آن را برای خواندن باز کند، بخواند و دوباره ببندد. سپس ممکن است TeX این فرآیند را برای بار دوم یا چندین بار تکرار کند و بارها و بارها از همان نام فایل استفاده مجدد کند. texprof هر بار که این فایل برای خواندن باز شود، شمارهٔ فایل جدیدی به آن اختصاص می‌دهد. بنابراین می‌توانید از روی توالی شماره‌های فایل تشخیص دهید کدام‌یک اولی، دومی یا سومی بوده است.

در نهایت، چند شمارهٔ فایل ویژه نیز وجود دارد:

0 - unknown
اگر فایل ناشناخته باشد، که به‌ندرت رخ می‌دهد، از شمارهٔ فایل 0 استفاده می‌شود.
1- system
برنامهٔ texprof بازه‌های زمانی را که برای اجرای روال‌های سیستمی خاصی صرف می‌شوند به شبه‌فایل «system» نگاشت می‌کند و از شماره‌خط‌ها برای شناسایی روال خاص استفاده می‌نماید؛ مانند تولید فایل خروجی DVI (روال shipout)، شکستن پاراگراف به خطوط (روال linebrk)، یا شکستن سند به صفحات (روال buildpg). این زمان‌ها به استفاده از ماکروها وابسته نیستند، بلکه صرفاً به اندازهٔ سند بستگی دارند.
2 - terminal
دستورات TeX که در خط فرمان یا به‌صورت تعاملی وارد می‌شوند به شمارهٔ فایل 2 نگاشت می‌گردند.

اگر گزینهٔ -m داده شود، زمان‌ها بر حسب نانوثانیه ارائه می‌شوند. در غیر این صورت، زمان‌ها حداکثر با دقت ۴ رقم گرد شده و با یک یکا (واحد) نمایش داده می‌شوند: ثانیه (s)، میلی‌ثانیه (ms)، میکروثانیه (um)، یا نانوثانیه (ns).

نام‌های ماکرو با بک‌اسلشِ پیشین نمایش داده می‌شوند. از آنجا که نام‌های ماکرو اغلب یکتا نیستند، می‌توان از گزینهٔ خط فرمان -i استفاده کرد تا پس از نام ماکرو در داخل قلاب‌ها، شمارهٔ فایل و شمارهٔ خطی که ماکرو در آن تعریف شده نمایش داده شود. مگر آنکه دو ماکرو با نام یکسان در همان فایل و همان خط تعریف شده باشند، این کار برای شناسایی یکتای یک ماکرو کافی است. ماکرویی که با «let» تعریف شود به یک رونوشت کامل از ماکروی اصلی منجر می‌گردد. بنابراین به فایل و خطِ دستور «let» ارجاع نخواهد داد، بلکه به همان فایل و خطِ ماکروی اصلی ارجاع می‌دهد.

فرض کنیم دستور زیر را اجرا می‌کنید: texprof -prof hello.tex. این کار texprof را بر روی فایل ورودی hello.tex با گزینهٔ -prof اجرا می‌کند. برنامهٔ texprof قالب plain TeX را بارگذاری کرده و سپس hello.tex را پردازش می‌کند تا hello.log و hello.dvi را تولید نماید. این برنامه دقیقاً همان مراحلی را اجرا خواهد کرد که اگر دستور زیر را اجرا می‌کردید TeX انجام می‌داد: tex hello.tex.

علاوه بر hello.log و hello.dvi، برنامهٔ texprof فایل hello.tprof را نیز تولید خواهد کرد که شامل اندازه‌گیری‌های زمانی انجام‌شده در هنگام اجرای texprof است. گزینهٔ -prof به محض ورود texprof به روال کنترلی اصلی‌اش، جمع‌آوری داده‌های زمان‌بندی را فعال می‌کند؛ فایل hello.tprof برای هر دستوری که TeX هنگام پردازش ورودی اجرا کرده است، شامل یک اندازه‌گیری زمانی، موسوم به برچسب زمان (time stamp)، خواهد بود. یک قالب دودویی (باینری) برای ذخیرهٔ تمام این داده‌ها به شکلی ساده و فشرده به کار گرفته می‌شود. با این حال ممکن است فایل hello.tprof بسیار حجیم شود.

برنامهٔ texprofile برای استخراج و تحلیل داده‌های موجود در hello.tprof و تولید خروجی سودمند به کار می‌رود. در اینجا چند مثال آورده شده است:


بدون گزینه‌های دیگر، texprofile برخی اطلاعات عمومی را در خروجی استاندارد می‌نویسد؛ مانند کل زمان اندازه‌گیری‌شده، تعداد نمونه‌ها، میانگین زمان به ازای هر نمونه، و غیره. اطلاعات عمومی همیشه ارائه می‌شوند مگر اینکه صریحاً با گزینهٔ -N یا با گزینهٔ -m غیرفعال شده باشند.

با گزینهٔ -T، برنامهٔ texprofile هر برچسب زمان را به خط خاصی از ورودی نگاشت می‌کند، بازه‌های زمانی را برای هر خط ورودی به‌طور جداگانه جمع می‌زند، و جدولی شامل ده خطی که بیشترین زمان تجمعی را دارند در خروجی نمایش می‌دهد. این جدول دارای هفت ستون زیر است:
1. file
ستون اول شامل شمارهٔ فایل ورودی است، همان‌طور که در بالا توضیح داده شد. نام فایل ورودی در ستون ۷ نمایش داده می‌شود.
2. line
شمارهٔ خط.
3. percent
زمان صرف‌شده در این خط و فایل به صورت درصدی از کل زمان اندازه‌گیری‌شده که به عنوان بخشی از اطلاعات عمومی ارائه می‌شود.
4. absolute
زمان مطلق صرف‌شده در این خط و فایل.
5. count
تعداد دفعاتی که مسیر اجرا وارد این خط شده است. توجه داشته باشید که یک فراخوانی ماکرو معمولاً مسیر اجرا را به خط دیگری هدایت می‌کند که اجرا پس از اتمام فراخوانی ماکرو از آنجا باز خواهد گشت. ورود مجدد به این خط پس از چنین گریز به خطی دیگر، باعث افزایش این شمارنده خواهد شد. به‌طور خلاصه، این شمارنده ممکن است منعکس‌کنندهٔ تعداد اجراهای جزئی یک خط باشد، نه تعداد اجراهای کامل کل خط.
6. average
میانگین زمان صرف‌شده در خط به‌سادگی از تقسیم مقدار ستون ۴ بر مقدار ستون ۵ محاسبه می‌شود.
7. file
نام فایل ورودی. شمارهٔ فایل مربوطه در ستون ۱ نمایش داده می‌شود.

با گزینهٔ -G، برنامهٔ texprofile هر برچسب زمان را یا به ورودی فایل یا به بدنهٔ یک ماکرو نگاشت می‌کند. جدول نمایش‌داده‌شده به چند بخش تقسیم می‌شود؛ بخش اول به ورودی فایل اختصاص دارد و هر یک از بخش‌های بعدی به یک ماکروی خاص اختصاص یافته است.
هر بخش با یک سرآیند آغاز می‌شود. سرآیند بخش اول «File» و سرآیند بخش‌های بعدی نام ماکرو است.
نخستین خط پس از سرآیند، کل زمان صرف‌شده در بخش را در دو قالب مختلف ارائه می‌دهد: 1. time ستون ۱ آن را به عنوان یک زمان مطلق ارائه می‌دهد.
3. percentage
ستون ۳ آن را به صورت درصدی از کل زمان اندازه‌گیری‌شده ارائه می‌دهد.

برای اولین بخش با سربرگ «File»، زمان مطلق برابر با کل زمان اندازه‌گیری‌شده خواهد بود، زیرا texprof تمام زمان را صرف پردازش فایل hello کرده است. و در نتیجه مقدار ستون ۳ برابر با 100% خواهد بود.
برای انجام یک وظیفه، یک ماکرو معمولاً ماکروهای دیگری را فراخوانی می‌کند که در ادامه آن‌ها را ماکروهای فرزند می‌نامیم. سطرهای بعدی در جدول، تفکیکی از زمان ارائه‌شده در سطر اول را نشان می‌دهند. این تفکیک با سطری آغاز می‌شود که زمان صرف‌شده در بخش را بدون در نظر گرفتن زمان صرف‌شده در ماکروهای فرزند نشان می‌دهد. این سطر در ستون ۴ تعداد دفعات فراخوانی ماکرو را نشان می‌دهد.

1. time
ستون ۱ زمان مطلقی را نشان می‌دهد که در بخش صرف شده است، به استثنای زمان صرف‌شده در ماکروهای فرزند.
3. percentage
ستون ۳ زمان ستون ۱ را به صورت درصدی از کل زمان صرف‌شده در این بخش، طبق آنچه در سطر قبلی آمده است، ارائه می‌دهد.
4. count/total
ستون ۴ تعداد دفعاتی را که بخش فراخوانی شده است نشان می‌دهد.

سطرهایی که در ادامه جدول می‌آیند، زمان صرف‌شده در یکی از ماکروهای فرزند را نشان می‌دهند. ستون‌های ۲، ۴ و ۵ نیاز به توضیح دارند.

2. loop
تنها حالتی که ستون ۲ خالی نیست، در صورت وجود یک ماکروی بازگشتی است. ماکروی بازگشتی ماکرویی است که در امتداد زنجیره فراخوانی‌های ماکرو در نهایت خود را فراخوانی کرده و یک حلقه بازگشتی ایجاد می‌کند. در این نقطه، ماکرو هم‌زمان فرزند خود و جد خود می‌شود.
بنابراین texprofile برای هر ماکروی فرزند دو انباشتگر برای زمان سپری‌شده نگه می‌دارد: برای زمان نشان‌داده‌شده در ستون ۲ با برچسب «loop»، برنامه texprofile اختلاف‌های زمانی مشاهده‌شده هنگام بازگشت ماکروی فرزند را جمع می‌زند. برای زمان نشان‌داده‌شده در ستون‌های برچسب‌خورده با «time» و «percent»، تمام اختلاف‌های زمانی را که قبلاً به یکی از سطرهای دیگر در تفکیک زمانی افزوده شده‌اند (خود ماکرو یا یکی از دیگر ماکروهای فرزند)، از اختلاف‌های زمانیِ دیده‌شده هنگام بازگشت ماکروی فرزند کسر می‌کند. بنابراین زمان‌های ارائه‌شده در ستون ۱ از سطر ۲ و سطرهای بعدی، در مجموع برابر با زمان نشان‌داده‌شده در ستون ۱ سطر ۱ خواهد بود؛ و درصدهای ارائه‌شده در ستون ۳ سطر ۲ و سطرهای بعدی نیز به 100% می‌رسند. زمان ارائه‌شده در ستون ۳، کل زمان مورد نیاز برای انجام وظیفه فرعیِ واگذارشده به ماکروی فرزند مربوطه را نشان خواهد داد.
4. count/total
ستون ۴ دو شمارش n/m را برای ماکروی نام‌برده در ستون ۵ نشان می‌دهد. m تعداد کل فراخوانی‌های ماکرو است و n تعداد فراخوانی‌ها به عنوان ماکروی فرزند در بخش فعلی است. مقدار n همواره کمتر یا مساوی با m خواهد بود.
5. child
ستون ۵ نام ماکروی فرزند را همان‌طور که در بالا توضیح داده شد نشان می‌دهد.

این جدول حاوی داده‌هایی مشابه مثال قبلی خواهد بود، اما این بار گزینه -m خروجی را برای خوانایی ماشین بهینه‌سازی می‌کند.
*
هیچ سربرگی برای ستون‌ها وجود ندارد.
*
زمان‌ها در ستون ۱ «time» و ستون ۲ «loop» به نانوثانیه و بدون شناسه یکا ارائه می‌شوند.
*
اعداد n/m در ستون ۴ اکنون در دو ستون مجزای ۴ و ۵ نمایش داده می‌شوند؛ نام ماکرو از ستون ۵ به ستون ۶ منتقل می‌شود.

با گزینه -F، برنامه texprofile جدول تمام فایل‌های ورودی TeX را با استفاده از ۵ ستون خروجی می‌دهد:
1. file
شماره فایل، همان‌طور که در بالا توضیح داده شد.
2. lines
اختلاف بین بالاترین و پایین‌ترین شماره خط دریافت‌شده در داده‌های پروفایل برای این فایل. این معمولاً تنها زیرمجموعه‌ای از تمام خطوط فایل است.
3. percent
درصدی از کل زمان اندازه‌گیری‌شده که به این فایل نسبت داده شده است.
4. time
زمان مطلقی که به این فایل نسبت داده شده است.
5. name
نام کامل فایل.

با گزینه -C، برنامه texprofile جدول تمام دستورات TeX اجراشده هنگام پروفایل‌سازی را با استفاده از ۶ ستون خروجی می‌دهد:
1. cmd
کد دستوری که به صورت داخلی توسط TeX استفاده می‌شود. معمولاً عدد یکسانی توسط TeX برای چندین وظیفه که ارتباط نزدیکی با یکدیگر دارند استفاده می‌شود. کد دستور ویژه‌ای با شماره 101 وجود دارد که برای زمان صرف‌شده روی روال‌های سیستمیِ نگاشت‌شده به فایل سیستم، مطابق توضیحات بالا، استفاده می‌شود.
2. time
کل زمان صرف‌شده برای دستور.
3. percent
درصدی از کل زمان اندازه‌گیری‌شده که برای دستور صرف شده است.
4. count
تعداد دفعاتی که این دستور اجرا شده است.
5. average
میانگین زمان مورد نیاز برای اجرای دستور. این مقدار به سادگی حاصل تقسیم مقدار ستون ۲ بر مقدار ستون ۴ است.
6. name
شرح متنی دستور یا دستوراتی که در این کد دستور مشترک هستند.

با گزینه‌های -R -m، برنامه texprofile جدول اندازه‌گیری‌های زمانی خام مشاهده‌شده توسط texprof را بهینه‌سازی‌شده برای خوانایی ماشین خروجی می‌دهد. گزینه -n ستونی برای شماره هر یک از اندازه‌گیری‌های زمانی اضافه می‌کند. به دلیل استفاده از گزینه -m، جدول فاقد سربرگ ستون‌ها است. این جدول دارای ۷ ستون است: 1. number شماره اندازه‌گیری زمان. این شماره‌ها اکیداً افزایشی هستند، اما لزوماً متوالی نیستند. می‌توان از آن‌ها برای مرتب نگه داشتن اندازه‌گیری‌ها به ترتیبی که انجام شده‌اند، استفاده کرد.
2. file
شماره فایل، همان‌طور که در بالا توضیح داده شد.
3. line
شماره خط، همان‌طور که در بالا توضیح داده شد.
4. time
بازه زمانی به نانوثانیه.
5. command
نام دستور، همان‌طور که در ستون ۶ مثال قبلی ارائه شد.
6. level
سطح تودرتویی پشته فراخوانی ماکرو.
7. macro
نام ماکرو.

این جدول حاوی تمام اطلاعات زمان‌بندی جمع‌آوری‌شده در حین اجرای texprof است. برخی اطلاعات درباره فراخوانی‌های ماکرو در ستون ۶ آمده است. اطلاعات بیشتر درباره فراخوانی‌های ماکرو را می‌توان با استفاده از گزینه -s اضافه کرد. اطلاعات مربوط به بازگشت ماکروها را می‌توان از ستون ۶ به دست آورد. این جدول را می‌توان برای تجزیه‌وتحلیل بیشتر به یک صفحه‌گسترده یا پایگاه داده وارد کرد.

اگر آخرین دستور در بدنه یک ماکرو یک فراخوانی ماکرو باشد، به آن فراخوانی انتهایی (tail call) می‌گوییم. اگر چنین tail callای برای پیمایش ورودی پس از خود به منظور یافتن آرگومان‌های احتمالی به جلو پیش‌خوانی کند، سازوکار پیش‌نگری (look-ahead) در TeX ممکن است ماکروهای بیشتر یا فایل‌های ورودی جدیدی را به پشته ورودی TeX وارد کند. این مدخل‌ها در بالای پشته تودرتویی ماکروی TeXprof باقی خواهند ماند، حتی اگر TeX تمام این نشانه‌ها (tokens) را در پشته ورودی خود بازگرداند. این امر می‌تواند باعث انتساب زمان اجرا به آن مدخل‌ها به عنوان زیرمدخل‌های tail call شود. اگر این توضیح به نظرتان پیچیده می‌آید، به این دلیل است که وضعیت واقعاً پیچیده است.

texprof(1)

نسخه: 1.1 مورخ 28-1-2025

کپی‌رایت
(C)2024, Martin Ruckert,
Hochschule München, Lothstrasse 64, D-80335 München
توزیع
texprofile همراه با TeX Live توزیع می‌شود. نسخه‌های جدیدتر را می‌توان در GitHub در https://github.com/ruckertm/HINT یافت.
مجوز
این برنامه را می‌توان تحت شرایط مجوز MIT/X11 بازتوزیع و/یا ویرایش کرد.

Martin Ruckert
دانشگاه علوم کاربردی مونیخ (Munich University of Applied Sciences)
ایمیل: martin.ruckert@hm.edu

28-1-2025 نمایش پروفایل‌های TeX