AUTOGSDOC(1) GNUstep System Manual AUTOGSDOC(1)

autogsdoc - تولیدکننده مستندات API گنو‌استپ (GNUstep) و تبدیل‌کننده XML به HTML

autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]

ابزار autogsdoc یک ابزار خط فرمانی است که به توسعه‌دهندگان در تولید مستندات مرجع برای رابط‌های برنامه‌نویسی کاربردی (API) گنو‌استپ (GNUstep) کمک می‌کند. این ابزار همچنین توسعه‌دهندگان را قادر می‌سازد تا سایر مستندات را در قالب XML نوشته و نگهداری کنند و سپس آن‌ها را به HTML تبدیل نمایند. به طور دقیق‌تر، autogsdoc کارهای زیر را انجام می‌دهد:

-
استخراج کامنت‌های ویژه‌ای که رابط‌های عمومی (public interfaces) کلاس‌ها، دسته‌بندی‌ها (categories)، پروتکل‌ها، توابع و ماکروها را از کد منبع Objective C (فایل‌های سرآیند و در صورت تمایل فایل‌های منبع) توصیف می‌کنند و ذخیره آن‌ها در فایل‌های GSDoc XML.
-
تبدیل فایل‌های GSDoc XML (چه از کد منبع تولید شده باشند و چه به‌صورت دستی توسط توسعه‌دهندگان نوشته شده باشند) به HTML.
-
ساخت نمایه‌ها (indices) بر اساس مجموعه‌های فایل GSDoc XML، و تبدیل آن‌ها نیز به HTML.

رایج‌ترین شیوه استفاده، اجرای دستور به همراه یک یا چند نام فایل سرآیند به‌عنوان آرگومان است ... این ابزار به‌طور خودکار فایل‌های منبع متناظر را در همان دایرکتوری فایل‌های سرآیند (یا دایرکتوری جاری، یا دایرکتوری مشخص‌شده از طریق پیش‌فرض DocumentationDirectory) تجزیه (parse) کرده و فایل‌های GSDoc و HTML را به‌عنوان خروجی تولید می‌کند. برای دستیابی به بهترین نتیجه، این حالت باید از داخل دایرکتوری حاوی فایل‌های منبع اجرا شود. (توجه داشته باشید از آنجا که C زیرمجموعه‌ای از Objective C است، این ابزار می‌تواند برای مستندسازی توابع و سایر ساختارهای C در کدهای منبع C خالص نیز به کار رود.)

فایل‌های GSDoc را نیز می‌توان علاوه بر موارد دیگر یا به‌تنهایی مستقیماً مشخص کرد، که در این صورت به HTML تبدیل خواهند شد. برای کسب اطلاعات درباره قالب GSDoc، به مستندات HTML مربوط به GSDoc یا صفحه راهنمای gsdoc(7) مراجعه کنید.

در نهایت، فایل‌های HTML نیز می‌توانند در خط فرمان مشخص شوند. ارجاعات متقابل (Cross-references) به بخش‌های دیگر مستندات کد که در آن‌ها یافت می‌شود، بر اساس آنچه در حال حاضر در پروژه موجود است، بازنویسی خواهند شد..SH نشانه‌گذاری کد منبع (SOURCE CODE MARKUP)

تجزیه‌گر کد منبع به‌طور خودکار اسناد GSDoc را تولید می‌کند که متدهای کلاس‌های یافت‌شده در فایل‌های منبع را فهرست کرده و متن‌های برگرفته از کامنت‌های با قالب‌بندی خاصِ درون فایل‌های منبع را در خود جای خواهد داد.

هر کامنتی که به جای اسلش و یک ستاره‌ی معمول، با یک اسلش و دو ستاره شروع شود، به عنوان نشانه‌گذاری GSDoc در نظر گرفته می‌شود تا به عنوان توضیحات کلاس یا متدی که پس از آن می‌آید استفاده شود. این متنِ کامنت بازقالب‌بندی شده و سپس در خروجی درج می‌گردد.

در مواردی که چند کامنت به یک مورد مشابه مرتبط باشند، در صورت نیاز با یک شکست خط (<br/>) در بین هر یک، به یکدیگر متصل می‌شوند.

این ابزار علاوه بر کتابخانه‌ها، می‌تواند به‌سادگی برای مستندسازی برنامه‌ها نیز به کار رود؛ کافی است نام فایل منبعِ حاوی تابع main() برنامه به آن داده شود - این ابزار کامنت‌های ویژه را از آن تابع برداشته و به‌طور خاص پردازش می‌کند، و آن‌ها را به عنوان یک بخش در انتهای فصل اول سند درج می‌نماید (در صورت نیاز، فصل اول را ایجاد می‌کند).

گزینه‌ها در بخش آرگومان‌ها و مقادیر پیش‌فرض (Arguments and Defaults) در زیر شرح داده شده‌اند.

مواردی وجود دارد که در آن‌ها پردازش‌های ویژه و اضافی انجام می‌شود؛ عمدتاً در اولین کامنتِ یافت‌شده در فایل منبع، که از آن ممکن است قطعه‌های گوناگونی از نشانه‌گذاری GSDoc استخراج شده و در مکان‌های مناسب در سند خروجی قرار گیرند -

در هر خطی که AutogsdocSource: یافت شود، ادامه‌ی خط به عنوان نام یک فایل منبع در نظر گرفته می‌شود تا به جای فرض این که هر فایل .h پردازش‌شده از یک فایل .m با همان نام استفاده می‌کند، به کار رود. می‌توانید چندین خط AutogsdocSource: را در جایی که یک فایل هدر مواردی را اعلان می‌کند که در چندین فایل منبع تعریف شده‌اند، مشخص کنید. اگر نام فایل مطلق باشد، دقیقاً همان‌گونه که ارائه شده استفاده می‌شود. از سوی دیگر، اگر یک مسیر نسبی باشد، نرم‌افزار ابتدا فایل منبع را نسبت به مکان فایل هدر جستجو می‌کند، و اگر در آنجا یافت نشد، نسبت به دایرکتوری جاری که autogsdoc در آن در حال اجراست، و در نهایت نسبت به دایرکتوری مشخص‌شده توسط مقدار پیش‌فرضِ DocumentationDirectory جستجو می‌نماید.
<abstract>
چکیده‌ای از محتوای سند ... در بخش head خروجی GSDoc قرار می‌گیرد.
<author>
شرحی از نویسنده‌ی کد - برای پشتیبانی از مواردی که یک سند دارای چندین نویسنده است، می‌تواند تکرار شود. در بخش head خروجی GSDoc قرار می‌گیرد. به منظور کمک به خوانایی کد منبع، برخی پردازش‌های اضافی و ویژه در رابطه با نویسنده‌ی سند انجام می‌شود - هر خطی به شکل 'Author: name <email-address>', یا 'By: name <email-address>', یا 'Author: name' یا 'By: name' شناسایی شده و به یک عنصر author تبدیل می‌شود که احتمالاً شامل یک عنصر email نیز خواهد بود.
<back>
درست پیش از پایان بدنه (body) سند در خروجی GSDoc قرار می‌گیرد - جهت استفاده برای ضمیمه‌ها، نمایه‌ها و غیره در نظر گرفته شده است.
<chapter>
بلافاصله پیش از هرگونه مستندات تولیدشده برای کلاس‌ها قرار می‌گیرد ... به منظور ارائه توضیحات کلی درباره نحوه کارکرد کدی که مستندسازی می‌شود، در نظر گرفته شده است. هرگونه مستندات برای تابع main() یک برنامه، به عنوان یک بخش در انتهای این فصل درج می‌شود.
<copy>
کپی‌رایت محتوای سند ... در بخش head خروجی GSDoc قرار می‌گیرد. برای کمک به خوانایی کد منبع، برخی پردازش‌های اضافی و ویژه انجام می‌گیرد - هر خطی به شکل 'Copyright (C) text' شناسایی شده و به یک عنصر copy تبدیل خواهد شد.
<date>
تاریخ ویرایش سند ... در بخش head خروجی GSDoc قرار می‌گیرد. در صورت حذف این مورد، ابزار تلاش خواهد کرد مقداری را از برچسب RCS Date (در صورت موجود بودن) بسازد.
<front>
در ابتدای بدنه (body) سند درج می‌شود ... جهت استفاده برای مقدمه، صفحات فهرست مطالب و غیره در نظر گرفته شده است.
<title>
عنوان سند ... در بخش head خروجی GSDoc قرار می‌گیرد. اگر این مورد حذف شود، ابزار عنوان خاص خود را (احتمالاً ضعیف) ایجاد خواهد کرد - بنابراین باید این نشانه‌گذاری را به‌صورت دستی وارد کنید.
<version>
شناسه نسخه سند ... در بخش head خروجی GSDoc قرار می‌گیرد. در صورت حذف این مورد، ابزار تلاش خواهد کرد مقداری را از برچسب RCS Revision (در صورت موجود بودن) بسازد.

نکته نشانه‌گذاری‌هایی که شرح داده شدند می‌توانند در مستندات class، category یا protocol نیز استفاده شوند ... اگر چنین باشد، استخراج شده و به عنوان فصل مربوط به کلاس، پیرامون سایر مستندات کلاس قرار می‌گیرند. بقیه مستندات کلاس معمولاً در انتهای فصل درج می‌شود، اما در عوض می‌تواند به جای شبه‌عنصر <unit> درون عنصر <chapter> جایگزین شود..SH "نشانه‌گذاری متد (METHOD MARKUP)"

در کامنت‌هایی که برای فراهم کردن متن جهت شرح متد به کار می‌روند، نشانه‌گذاری‌های زیر از متن حذف شده و به طور ویژه مدیریت می‌شوند:

<init>
متد به عنوان مقداردهی اولیه تخصیص‌یافته (designated initialiser) برای کلاس علامت‌گذاری می‌شود.
<override-subclass>
متد به عنوان متدی علامت‌گذاری می‌شود که زیرکلاس‌ها باید آن را بازنویسی (override) کنند (مثلاً یک متد انتزاعی).
<override-never>
متد به عنوان متدی علامت‌گذاری می‌شود که زیرکلاس‌ها نباید آن را بازنویسی کنند.
<standards>
نشانه‌گذاری از توضیحات حذف شده و در خروجی GSDoc در پس از آن قرار می‌گیرد - به‌طوری که متد به عنوان منطبق بودن (یا منطبق نبودن) با استانداردهای مشخص‌شده توصیف گردد.

به‌طور کلی، متن موجود در کامنت‌ها برای استانداردسازی و ایجاد تورفتگی مناسب بازقالب‌بندی می‌شود... این بازقالب‌بندی روی هیچ متنی درون یک عنصر <example> انجام نمی‌شود. هنگامی که متن بازقالب‌بندی می‌شود، به “کلمات” جداشده با فاصله (whitespace) تقسیم می‌گردد که سپس تحت پردازش‌های تکمیلی قرار می‌گیرند...

ثابت‌های شناخته‌شدهٔ خاصی مانند YES، NO و nil درون نشانه‌گذاری <code> ... </code> قرار می‌گیرند.
نام‌های آرگومان‌های متد در شرح متد درون نشانه‌گذاری <var> ... </var> قرار می‌گیرند.
نام‌های متد (که با یک مثبت یا منفی آغاز می‌شوند) درون نشانه‌گذاری <ref...> ... </ref> قرار می‌گیرند. برای مثال، "-init" (بدون علامت‌های نقل‌قول) درون یک عنصر ارجاع GSDoc پیچیده می‌شود تا به متد init کلاس فعلی اشاره کند، یا اگر تنها یک کلاس شناخته‌شده دارای متد init باشد، به متد آن کلاس ارجاع می‌دهد. به این نکته توجه داشته باشید که نام متد برای شناخته شدن باید با فاصله سفید احاطه شده باشد (اگرچه ویرگول، نقطه یا نقطه‌ویرگول در انتهای مشخص‌کننده مانند فاصله سفید عمل خواهند کرد).
مشخص‌کننده‌های متد شامل نام‌های کلاس (که با قلاب‌های باز و بسته شروع و پایان می‌یابند) درون نشانه‌گذاری <ref...> ... </ref> قرار می‌گیرند. برای مثال، '[NSObject-init]' ارجاعی به متد init از NSObject ایجاد می‌کند (چه خود کلاس اصلی، چه هر یک از دسته‌بندی‌های آن)، در حالی که '[(NSCopying)-copyWithZone:]' یک ارجاع به متدی در پروتکل NSCopying ایجاد می‌کند. توجه داشته باشید که هیچ فاصله‌ای نباید بین قلاب‌ها در این مشخص‌کننده‌ها قرار گیرد. نام‌های پروتکل به جای قلاب‌های زاویه‌دارِ معمول در پرانتزهای گرد قرار می‌گیرند، زیرا GSDoc یک زبان XML است و XML با قلاب‌های زاویه‌دار برخورد خاصی دارد.
نام‌های تابع (که با '()' خاتمه می‌یابند) غیر از 'main()' درون نشانه‌گذاری <ref...> ... </ref> قرار می‌گیرند. برای مثال، "NSLogv()" (بدون علامت‌های نقل‌قول) درون یک عنصر ارجاع GSDoc پیچیده خواهد شد تا به مستندات تابع NSLog اشاره کند. به این نکته توجه داشته باشید که نام تابع باید با فاصله سفید احاطه شده باشد (اگرچه ویرگول، نقطه یا نقطه‌ویرگول در انتهای مشخص‌کننده نیز به عنوان پایان‌دهندهٔ فاصله عمل خواهد کرد).

این ابزار پیش‌فرض‌های کاربری (user defaults) خاصی را می‌پذیرد (که البته می‌توانند به عنوان آرگومان‌های خط فرمان با قرار دادن '-' پیش از نام پیش‌فرض و ارائه مقدار پس از آن، مانند -Clean YES ارائه شوند):

اگر این مقدار بولی روی YES تنظیم شود، ابزار به جای تولید مستندات، تمام فایل‌های GSDoc تولیدشده در پروژه و تمام فایل‌های html ایجادشده از آن‌ها را (و نیز هر فایلی که از فایل‌های GSDoc فهرست‌شده به‌صراحت تولید می‌شد) حذف می‌کند، و در پایان فایل نمایه‌سازی (index) پروژه را حذف می‌نماید. تنها استثنا در این خصوص این است که فایل‌های قالب GSDoc (یعنی مواردی که با استفاده از آرگومان‌های "-ConstantsTemplate ..." ،"FunctionsTemplate -" و غیره مشخص شده‌اند) حذف نمی‌شوند مگر اینکه پرچم CleanTemplates تنظیم شده باشد.
این پرچم مشخص می‌کند که آیا هنگام مشخص شدن گزینهٔ Clean، فایل‌های قالب GSDoc همراه با سایر فایل‌ها حذف شوند یا خیر. پیش‌فرض این است که حذف نشوند... چرا که این قالب‌ها ممکن است به‌طور دستی ساخته شده و داده‌ها صرفاً درون آن‌ها درج شده باشند.
نام یک سند قالب را مشخص می‌کند که مستندات مربوط به ثابت‌ها باید از تمام فایل‌های پروژه در آن درج شوند. این مورد هنگامی مفید است که ثابت‌ها در کد منبع میان فایل‌های زیادی پراکنده شده باشند و شما نیاز داشته باشید آن‌ها را در یک مکان گروه‌بندی کنید. اطمینان از اینکه سند قالب اولیه (که مستندات تک‌تک ثابت‌ها در آن درج می‌شود) شامل سایر اطلاعات مورد نظر شما باشد بر عهدهٔ شماست، اما جهت سهولت، در صورتی که فایل وجود نداشته باشد autogsdoc یک قالب ساده (که می‌توانید سپس آن را ویرایش کنید) برای شما تولید خواهد کرد. درج دقیقاً پیش از عنصر back (یا در صورت عدم وجود، دقیقاً پیش از انتهای عنصر body) در قالب رخ می‌دهد.
مشخص می‌کند که هدرها در مستندات به عنوان محل استقرار در کجا ثبت شوند. نام واقعی تولیدشده در مستندات با الحاق آخرین بخش از نام فایل هدر به مقدار این پیش‌فرض تشکیل می‌شود. اگر این پیش‌فرض مشخص نشده باشد، نام کامل فایل هدر (همان‌طور که در خط فرمان ارائه شده)، با پیشوند پیش‌فرض HeaderDirectory استفاده می‌شود. یک کاربرد معمول آن هنگام تولید مستندات برای کتابخانه پایه GNUstep ممکن است به صورت '"-Declared Foundation";' باشد. این کار باعث می‌شود مستندات اعلام کنند که NSString در 'Foundation/NSString.h' اعلان شده است.
این پرچم به شما اجازه می‌دهد تا برای تمام متغیرهای نمونه (instance variables) مستندات تولید کنید. به‌طور معمول، فقط مواردی که صراحتاً به عنوان 'public' یا 'protected' اعلان شده باشند مستندسازی خواهند شد.
این پرچم به شما امکان می‌دهد مستندسازی برای متغیرهای نمونه را به طور کامل غیرفعال کنید. به‌طور معمول، متغیرهای نمونه‌ای که صراحتاً به صورت 'public' یا 'protected' اعلان شده باشند مستندسازی می‌شوند.
این پرچم، در صورت تنظیم، به تولیدکننده HTML هدایت می‌کند که مستندات متغیرهای نمونه را به جای ابتدای کلاس، در انتهای آن قرار دهد. این ویژگی زمانی مفید است که از متغیرهای نمونه محافظت‌شده (protected) زیادی استفاده می‌کنید که برای کاربران عمومی کلاس تنها اهمیت ثانویه دارند.
می‌تواند برای مشخص کردن دایرکتوری‌ای که مستندات تولیدشده باید در آن قرار گیرند استفاده شود. اگر این مقدار تنظیم نشده باشد، خروجی در دایرکتوری فعلی قرار می‌گیرد. این دایرکتوری همچنین به عنوان آخرین راهکار برای یافتن فایل‌های منبع (نه هدرها) استفاده می‌شود، و مهم‌تر از آن، به عنوان نخستین و تنها راهکار برای یافتن هرگونه فایل .gsdoc که در خط فرمان ارسال شده‌اند، استفاده می‌شود. هرگونه اطلاعات مسیر ارائه شده برای این فایل‌ها حذف شده و جستجو برای آن‌ها در 'DocumentationDirectory' انجام می‌شود (حتی اگر به‌طور خودکار تولید نشده باشند).
نام فایلی را مشخص می‌کند که حاوی فهرستی از نام‌های فایل در قالب یک آرایه property list به فرمت (name1,name2,...) است. در صورت وجود این گزینه، نام‌های فایل در فهرست آرگومان‌های برنامه نادیده گرفته شده و نام‌های درون این فایل به عنوان فهرست نام‌های مورد پردازش استفاده می‌شوند.
نام یک سند قالب را مشخص می‌کند که مستندات مربوط به توابع باید از تمام فایل‌های پروژه در آن درج شوند. این مورد زمانی مفید است که کد منبع توابع در فایل‌های زیادی پراکنده شده باشد و شما نیاز به گروه‌بندی آن‌ها در یک مکان داشته باشید. اطمینان از اینکه سند قالب اولیه (که مستندات توابع جداگانه در آن درج می‌شود) شامل تمام اطلاعات دیگر مورد نظر شما باشد بر عهدهٔ شماست، اما برای سهولت، در صورتی که فایل وجود نداشته باشد، autogsdoc یک قالب ساده (که بعداً می‌توانید آن را ویرایش کنید) برای شما ایجاد خواهد کرد. درج دقیقاً پیش از عنصر back (یا در صورت عدم وجود، دقیقاً پیش از انتهای عنصر body) در قالب رخ می‌دهد.
می‌تواند برای مشخص کردن اینکه آیا خروجی HTML باید تولید شود یا خیر به کار رود. پیش‌فرض بر روی YES است.
می‌تواند برای مشخص کردن دایرکتوری مورد جستجو جهت فایل‌های هدر استفاده شود. در صورت ارائه، این مقدار به نام‌های هدر نسبی اضافه می‌شود (پیشوند می‌گردد)، در غیر این صورت نام‌های هدر نسبی بر اساس دایرکتوری فعلی تفسیر می‌شوند. فایل‌های هدر که به صورت مسیرهای مطلق مشخص شده‌اند تحت تأثیر این پیش‌فرض قرار نمی‌گیرند.
یک مقدار بولی که می‌تواند برای تعیین اینکه برنامه باید زمان‌های تغییر فایل را نادیده گرفته و فایل‌ها را در هر صورت مجدداً تولید کند استفاده شود. این قابلیت برای استفاده در هماهنگی با سامانه 'make' در نظر گرفته شده است، که انتظار می‌رود خود بررسی وابستگی‌ها را مدیریت کند.
این مقدار برای کنترل گنجاندن خودکار پروژه‌های خارجی محلی در سامانه نمایه‌سازی جهت تولید ارجاع‌های متقابل (cross-references) در خروجی سند نهایی استفاده می‌شود. اگر بر روی 'None' تنظیم شود، هیچ ارجاعی به پروژه‌های محلی انجام نمی‌شود، در غیر این صورت، دایرکتوری مستندات 'Local' در GNUstep به‌صورت بازگشتی برای یافتن فایل‌هایی با پسوند '.igsdoc' جستجو می‌شود و از اطلاعات نمایه‌سازی آن فایل‌ها استفاده می‌گردد. مقدار این رشته همچنین برای تولید نام‌های فایل در ارجاع متقابل استفاده می‌شود... اگر رشته‌ای خالی باشد، مسیر مورد استفاده، یک فایل در همان دایرکتوری که فایل igsdoc یافت شده در نظر گرفته می‌شود، در غیر این صورت به عنوان یک پیشوند برای نام موجود در نمایه استفاده می‌شود. نکته: پروژه‌های محلی با همان نام پروژه‌ای که در حال حاضر مستندسازی می‌شود، توسط این سازوکار گنجانده نخواهند شد. اگر می‌خواهید چنین پروژه‌هایی را بگنجانید، باید صراحتاً با استفاده از -Projects ... این کار را انجام دهید..IP "MacrosTemplate" 4 نام یک سند الگو را مشخص می‌کند که مستندات مربوط به ماکروها از تمامی فایل‌های پروژه در آن درج می‌شوند. این ویژگی زمانی مفید است که کد ماکروها در چندین فایل پراکنده شده باشد و نیاز داشته باشید آن را در یک جا گروه‌بندی کنید. مسئولیت اطمینان از اینکه سند الگوی پایه (که مستندات مجزای هر ماکرو در آن درج می‌شود) حاوی تمام اطلاعات دیگری که می‌خواهید باشد بر عهده شماست، اما جهت سهولت، در صورتی که فایل وجود نداشته باشد، autogsdoc یک الگوی ساده (که بعداً می‌توانید آن را ویرایش کنید) برای شما تولید خواهد کرد. عملیات درج درست پیش از عنصر back (یا در صورت عدم وجود آن، درست پیش از پایان عنصر body ) در الگو انجام می‌گیرد.
نام فایلی که برای خروجی دادن اطلاعات وابستگی برای make استفاده می‌شود. این خروجی به شکل فهرستی از تمام فایل‌های هدر و سورس شناخته‌شده برای پروژه، به عنوان وابستگی‌های نام پروژه خواهد بود (نگاه کنید به 'Project').
می‌تواند برای تعیین نام این پروژه به کار رود ... نام فایل مرجع نمایه (index) تولید شده به عنوان بخشی از مستندات را مشخص می‌کند تا اطلاعاتی فراهم کند که سایر پروژه‌ها بتوانند به موارد موجود در این پروژه ارجاع متقابل (cross-reference) دهند.
این مقدار می‌تواند به عنوان یک دیکشنری حاوی مسیرهای فایل‌های نمایه/مرجع igsdoc که توسط پروژه‌های خارجی استفاده می‌شوند، به همراه مقادیری برای نگاشت نام فایل‌های یافت‌شده در نمایه‌ها ارائه شود. برای نمونه، اگر فایل نمایه یک پروژه (igsdoc) اعلام کند که کلاس 'Foo' در فایل 'Foo' قرار دارد و مسیر مرتبط با آن نمایه پروژه '/usr/doc/proj' باشد، آن‌گاه خروجی html تولیدشده ممکن است به کلاس در '/usr/doc/prj/Foo.html' ارجاع دهد. توجه داشته باشید که دیکشنری را می‌توان در خط فرمان با استفاده از قالب استاندارد PropertyList (نه قالب XML متعلق به OS X)، با استفاده از نقطه‌ویرگول به عنوان جداکننده خطوط و قرار دادن آن در علامت نقل‌قول تکی ارائه داد.
یک مقدار بولی که می‌تواند برای تعیین اینکه آیا برنامه باید بازتولید فایل‌ها به دلیل وابستگی آن‌ها به فایل‌های دیگر را ثبت (log) کند یا خیر، استفاده شود.
یک مقدار بولی که مشخص می‌کند آیا برنامه باید اطلاعات مربوط به سازگاری با استانداردها را در مستندات درج کند یا خیر. این گزینه تنها باید هنگام مستندسازی خود کتابخانه‌ها و ابزارهای GNUstep استفاده شود؛ زیرا فرض می‌کند کدی که مستند می‌شود بخشی از GNUstep است و احتمالاً با استاندارد OpenStep مطابقت دارد یا متدهای سازگار با MacOS-X را پیاده‌سازی می‌کند.
این مقدار برای کنترل گنجاندن خودکار پروژه‌های خارجی سیستم در سامانه نمایه‌سازی جهت ایجاد ارجاعات متقابل در خروجی نهایی سند استفاده می‌شود. اگر بر روی 'None' تنظیم شود، هیچ ارجاعی به پروژه‌های سیستم انجام نمی‌گیرد؛ در غیر این صورت، دایرکتوری مستندات 'System' در GNUstep به‌صورت بازگشتی برای یافتن فایل‌هایی با پسوند '.igsdoc' جستجو شده و اطلاعات نمایه‌سازی از آن فایل‌ها مورد استفاده قرار می‌گیرد. مقدار این رشته همچنین برای تولید نام فایل‌ها در ارجاع متقابل استفاده می‌شود ... اگر یک رشته خالی باشد، مسیر مورد استفاده فایلی در همان دایرکتوری در نظر گرفته می‌شود که فایل igsdoc در آن یافت شده است؛ در غیر این صورت به عنوان پیشوندی برای نام موجود در نمایه به کار می‌رود. نکته: پروژه‌های سیستمی که نامی یکسان با پروژه در حال مستندسازی دارند، توسط این سازوکار گنجانده نخواهند شد. اگر می‌خواهید چنین پروژه‌هایی را بگنجانید، باید صریحاً با استفاده از -Projects ... این کار را انجام دهید.
نام یک سند الگو را مشخص می‌کند که مستندات مربوط به typedefها از تمامی فایل‌های پروژه در آن درج می‌شوند. این ویژگی زمانی مفید است که کد مبدأ typedef در چندین فایل پراکنده شده باشد و بخواهید آن را در یک جا گروه‌بندی کنید. مسئولیت اطمینان از اینکه سند الگوی پایه (که مستندات مجزای هر typedef در آن درج می‌شود) حاوی تمام اطلاعات دیگری که می‌خواهید باشد بر عهده شماست، اما جهت سهولت، در صورتی که فایل وجود نداشته باشد، autogsdoc یک الگوی ساده (که بعداً می‌توانید آن را ویرایش کنید) برای شما تولید خواهد کرد. عملیات درج درست پیش از عنصر back (یا در صورت عدم وجود آن، درست پیش از پایان عنصر body ) در الگو انجام می‌گیرد.
رشته‌ای که نام مورد استفاده در پیوند 'up' اسناد تولیدشده GSDoc را تأمین می‌کند. این مقدار معمولاً باید نام فایلی باشد که حاوی نمایه‌ای از محتویات یک پروژه است. اگر این مقدار داده نشود یا روی یک رشته خالی تنظیم شود، هیچ پیوند 'up' در اسناد ارائه نخواهد شد.
نام یک سند الگو را مشخص می‌کند که مستندات مربوط به متغیرها از تمامی فایل‌های پروژه در آن درج می‌شوند. این ویژگی زمانی مفید است که کد مبدأ متغیرها در چندین فایل پراکنده شده باشد و بخواهید آن را در یک جا گروه‌بندی کنید. مسئولیت اطمینان از اینکه سند الگوی پایه (که مستندات مجزای هر متغیر در آن درج می‌شود) حاوی تمام اطلاعات دیگری که می‌خواهید باشد بر عهده شماست، اما جهت سهولت، در صورتی که فایل وجود نداشته باشد، autogsdoc یک الگوی ساده (که بعداً می‌توانید آن را ویرایش کنید) برای شما تولید خواهد کرد. عملیات درج درست پیش از عنصر back (یا در صورت عدم وجود آن، درست پیش از پایان عنصر body ) در الگو انجام می‌گیرد.
یک مقدار بولی برای مشخص کردن این که آیا می‌خواهید خروجی پرگو اشکال‌زدایی/هشدار تولید شود یا خیر.
یک مقدار بولی برای مشخص کردن این که آیا می‌خواهید خروجی هشدارهای استاندارد (مانند گزارش متدهای مستندنشده) تولید شود یا خیر.
این مقدار یک دیکشنری است که برای نگاشت شناسه‌ها/کلمات کلیدی یافت‌شده در فایل‌های مبدأ به کلمات دیگر استفاده می‌شود. به‌طور کلی نیازی به استفاده از این مقدار نخواهید داشت، اما گاهی اوقات برای جلوگیری از سردرگمی تجزیه‌کننده (parser) در اثر استفاده از ماکروهای پیش‌پردازنده C مفید است. می‌توانید به‌طور مؤثری ماکرو را به چیزی با ابهام کمتر بازتعریف کنید. مقداری که شناسه را به آن نگاشت می‌کنید باید یکی از موارد زیر باشد: - یک شناسه دیگر، یک رشته خالی - مقدار نادیده گرفته می‌شود، دو اسلش ('//') - بقیه خط نادیده گرفته می‌شود. توجه داشته باشید که دیکشنری را می‌توان در خط فرمان با استفاده از قالب استاندارد PropertyList (نه قالب XML متعلق به OS X)، با استفاده از نقطه‌ویرگول به عنوان جداکننده خطوط و قرار دادن آن در علامت نقل‌قول تکی ارائه کرد..SH "پیوند میان‌سندی (INTER-DOCUMENT LINKAGE)"

مقدار پیش‌فرض 'Up' برای مشخص کردن نام سندی به کار می‌رود که باید به عنوان پیوند «بالا» ('up') برای هر سند مورد استفاده‌ی دیگری به کار رود. این نام نباید شامل مسیر یا پسوند باشد. به طور کلی، سندی که این مقدار پیش‌فرض به آن ارجاع می‌دهد باید یک سند GSDoc ویرایش‌شده به صورت دستی باشد که دارای بخش <em>back</em> حاوی نمایه‌ی پروژه است؛ برای مثال:

<?xml version="1.0"?>

<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"

"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">

<head>

<title>My project reference</title>

<author name="my name"></author>

</head>

<body>

<chapter>

<heading>My project reference</heading>

</chapter>

<back>

<index scope="project" type="title" />

</back>

</body>
</gsdoc>

منبع: .h, .m, .c

GSDoc: .gsdoc
نمایه: .igsdoc
HTML: .html

چندین عنصر GSDoc هنوز به درستی به HTML رندر نمی‌شوند. این عناصر عبارتند از: <prjref>، <EOEntity>، <EOModel>.

پیام‌های خطا و هشدارها می‌توانند از هر یک از مراحل این خط لوله ناشی شوند: کنترل سطح بالا، تجزیه‌ی منبع، تجزیه‌ی GSDoc و نمایه‌سازی.

gsdoc(7), GNUstep(7)

ابزار Autogsdoc قابلیت‌های دو ابزار پیشین، یعنی 'autodoc' و 'gsdoc' را ترکیب کرد که به ترتیب تبدیل‌های source->GSDoc و GSDoc->HTML را انجام می‌دادند. این ابزارهای پیشین و قالب GSDoc بر پایه‌ی زبان قبلی GDML SGML برای GNUstep توسعه یافته بودند.

این صفحه راهنما نخستین بار در gnustep-base 1.9.2 (مارس ۲۰۰۴) منتشر شد.

autogsdoc توسط Richard Frith-Macdonald <rfm@gnu.org> نوشته شده است.

این صفحه راهنما توسط Adrian Robert <arobert@cogsci.ucsd.edu> اضافه شده است.

March 2004 GNUstep