प्लेन ओल्ड डॉक्यूमेंटेशन

प्लेन ओल्ड डॉक्यूमेंटेशन (पॉड) लाइटवेट मार्कअप लैंग्वेज है जिसका उपयोग पर्ल प्रोग्रामिंग लैंग्वेज के साथ-साथ पर्ल मॉड्यूल और प्रोग्राम को डॉक्यूमेंट (दस्तावेज) करने के लिए किया जाता है।

डिज़ाइन

पॉड को उपयोगी होने के लिए पर्याप्त वाक्यविन्यास के साथ सरल, क्लीन लैंग्वेज के रूप में डिज़ाइन किया गया है। इसमें उद्देश्यपूर्ण ढंग से फ़ॉन्ट, चित्र, रंग या तालिकाओं के लिए तंत्र सम्मिलित नहीं हैं। इसके कुछ लक्ष्य हैं:

• विश्लेषण करना आसान
• एक्सएमएल, टीईएक्स या मार्कडाउन जैसे अन्य प्रारूपों में परिवर्तित करना आसान है
• सैंपल कोड सम्मिलित करना आसान है
• पॉड फ़ॉर्मेटर के बिना पढ़ना आसान है (अर्थात इसके स्रोत-कोड रूप में)
• लिखना आसान है

विशेष रूप से लैरी वॉल, टॉम क्रिस्टियनसेन और जॉन ऑरवंत द्वारा प्रोग्रामिंग पर्ल पॉड का विस्तारित संस्करण जो स्यूडोपीओडी नामक तालिकाओं और फ़ुटनोट्स का समर्थन करता है, का उपयोग ओ'रेली एंड एसोसिएट्स द्वारा कई पर्ल पुस्तकों का उत्पादन करने के लिए किया गया है।

पॉड मैनपेज लिखना आसान बनाता है, जो उपयोगकर्ता-उन्मुख डॉक्यूमेंट के लिए उपयुक्त है। इसके विपरीत, अन्य डॉक्यूमेंट प्रणालियाँ, जैसे कि पायथन की डॉकस्ट्रिंग या जावा की जावाडोक, चूंकि उनका उपयोग उपयोगकर्ता डॉक्यूमेंटेशन के लिए किया जा सकता है, सॉफ़्टवेयर प्रोजेक्ट के लिए स्रोत कोड के बारे में डेवलपर-उन्मुख डॉक्यूमेंट तैयार करने की सुविधा के लिए डिज़ाइन की गई हैं।

उपयोग

पॉड पर्ल दुनिया में अधिकांश डॉक्यूमेंटेशन के लिए उपयोग की जाने वाली लैंग्वेज है। इसमें स्वयं पर्ल, लगभग सभी सार्वजनिक रूप से जारी पर्ल मॉड्यूल, कई स्क्रिप्ट (कंप्यूटर प्रोग्रामिंग), अधिकांश डिज़ाइन डॉक्यूमेंट, Perl.com पर कई लेख और अन्य पर्ल-संबंधित वेब साइटें और पैरेट वर्चुअल मशीन सम्मिलित हैं।

पॉड को अपरिष्कृत रूप में शायद ही कभी पढ़ा जाता है, हालाँकि इसे संरूपण उपकरण की सहायता के बिना पढ़ने योग्य बनाने के लिए डिज़ाइन किया गया है। इसके अतिरिक्त, इसे इसके साथ पढ़ा जाता है पेरलडॉ उपकरण, या यूनिक्स मैन पेज या वेब-मानक एचटीएमएल पेज में परिवर्तित किया गया।

पर्ल के अतिरिक्त अन्य संदर्भों में पॉड का उपयोग करना भी संभव है। उदाहरण के लिए, बैश (यूनिक्स शेल) में सरल डॉक्यूमेंट जोड़ना, जिसे बाद में आसानी से मैन पेजों में परिवर्तित किया जा सकता है। ऐसे उपयोग पॉड भाग को छिपाने के लिए लैंग्वेज-विशिष्ट हैक पर निर्भर करते हैं, जैसे (बैश में) लाइन के साथ पॉड अनुभाग को उपसर्ग करना :<<=cutजो पूरे ब्लॉक के साथ बैश के नो-ऑप : कमांड को कॉल करके काम करता है पॉड को यहां एक डॉक्यूमेंट के रूप में इनपुट के रूप में देखें।

शुद्ध पॉड फ़ाइलों में सामान्यतः एक्सटेंशन .पॉड होता है, लेकिन पॉड का उपयोग ज्यादातर सीधे पर्ल कोड में किया जाता है, जो सामान्यतः .pl और .pm एक्सटेंशन का उपयोग करता है। (पर्ल दुभाषिया (कंप्यूटिंग) के पद निरूपण को पर्ल कोड में पॉड को अनदेखा करने के लिए डिज़ाइन किया गया है।) स्रोत कोड फ़ाइलों में, डॉक्यूमेंटेशन को आम तौर __END__ मार्कर के बाद रखा जाता है (जो इसे टिप्पणियों के रूप में प्रदर्शित करने के लिए कुछ संपादकों में सिंटैक्स हाइलाइटिंग में भी मदद करता है)।

पॉड को आसानी से अन्य प्रारूपों में परिवर्तित किया जा सकता है, उदाहरण के लिए कुछ विभिन्न विकी प्रारूप जैसे: विकिविकिवेब, क्विकी, ट्विकी, यूजमोडविकी, टिडलीविकी, टेक्सटाइल (मार्कअप लैंग्वेज), मीडियाविकि, मोइन मोइन या कॉन्फ्लुएंस, पॉड::सिंपल::विकी का उपयोग करके किया जा सकता है।

उदाहरण

यह डॉक्यूमेंट वाक्यात्मक रूप से सही पॉड है, जो अनुभाग नामकरण पर प्रमुख परंपराओं का भी पालन करने का प्रयास करता है।

Source code

=head1 NAME

My::Module - An example module

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 LICENSE

This is released under the Artistic 
License. See L<perlartistic>.

=head1 AUTHOR

Juerd - L<http://juerd.nl/>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut

स्वरूपण विवरण

पॉड फ़ाइलें आस्की-संगत अक्षर कोडन में लिखी जाती हैं, जैसे लैटिन -1 या यूटीएफ-8। एक पॉड पद निरूपण हमेशा मानता है कि जिस फ़ाइल को वह विश्लेषण कर रहा है वह पॉड से प्रारंभ नहीं होती है; यह सभी पंक्तियों को अनदेखा करता है जब तक यह पॉड निर्देश नहीं देखता। पॉड निर्देश पंक्ति की प्रारंभ में आने चाहिए, और सभी एक समान चिह्न से प्रारंभ होने चाहिए। पॉड पद निरूपण तब मान लेगा कि निम्नलिखित सभी पंक्तियाँ पॉड हैं, जब तक कि उसे "= कट" निर्देश वाली पंक्ति का सामना न करना पड़े। इसके बाद की किसी भी सामग्री को तब तक नजरअंदाज कर दिया जाता है जब तक पद निरूपण को किसी अन्य पॉड निर्देश का सामना नहीं करना पड़ता। इस प्रकार, पॉड को निष्पादन योग्य स्रोत कोड के साथ अन्तर्मिश्र किया जा सकता है यदि लैंग्वेज का पद निरूपण पॉड को पहचानना और अनदेखा करना जानता है।

पॉड सामग्री को खाली पंक्तियों द्वारा पैराग्राफ में विभाजित किया गया है। जो पैराग्राफ व्हाईटस्पेस वर्ण कैरेक्टर्स-टैब या स्पेस-से प्रारंभ होते हैं, उन्हें शब्दशः पैराग्राफ माना जाता है, और उन्हें पूरी तरह से बिना स्वरूपित छोड़ दिया जाता है; इनका उपयोग सैंपल कोड, आस्की कला आदि के लिए किया जाता है। जो पैराग्राफ समान चिह्न से प्रारंभ होते हैं वे "कमांड पैराग्राफ" होते हैं; समान चिह्न के तुरंत बाद वर्णांक वर्णों के अनुक्रम को पॉड निर्देश के रूप में माना जाता है, और शेष पैराग्राफ को उस निर्देश के अनुसार स्वरूपित किया जाता है। कुछ निर्देश निम्नलिखित अनुच्छेदों को भी प्रभावित करते हैं। यदि कोई पैराग्राफ किसी समान चिह्न या रिक्त स्थान के अतिरिक्त किसी अन्य चीज़ से प्रारंभ होता है, तो इसे सामान्य पैराग्राफ माना जाता है।

सामान्य पैराग्राफ और कमांड पैराग्राफ की सामग्री दोनों को संरूपण कोड के लिए विश्लेषण किया जाता है। पॉड में संरूपण बहुत सरल है; यह मुख्य रूप से बोल्ड, इटैलिक, रेखांकित, मोनोस्पेस्ड और कुछ अन्य प्रारूपों तक सीमित है। पॉड डॉक्यूमेंट के बीच या उसी डॉक्यूमेंट के किसी अन्य अनुभाग से लिंक करने के लिए कोड भी है। संरूपण कोड में से कोई एक होता है:

• एकल अपरकेस अक्षर, उसके बाद कम-से-चिह्न (<), स्वरूपित की जाने वाली सामग्री, और एक बड़े-से-अधिक चिह्न (>), उदाहरण के लिए B<bolded text>, या
• एकल अपरकेस अक्षर, दो या दो से अधिक कम-से-चिह्न (<<), स्थान, स्वरूपित की जाने वाली सामग्री, अन्य स्थान, और पहले उपयोग किए गए समान संख्या में बड़े-से-अधिक संकेत, उदाहरण के लिए B<< bolded text >>, इस फॉर्म का उपयोग अधिकांशतः उन कोड स्निपेट्स के लिए किया जाता है जिनमें ग्रेटर-दैन चिह्न होता है, जो अन्यथा संरूपण कोड को समाप्त कर देगा।

पॉड में कमांड में शीर्षकों के चार स्तर, बुलेटेड और क्रमांकित सूचियां, और अनुभागों को किसी अन्य लैंग्वेज में चिह्नित करने के कमांड सम्मिलित हैं। बाद वाली सुविधा इसका समर्थन करने वाले पार्सर्स को विशेष स्वरूपण देने की अनुमति देती है।

यह भी देखें

• डॉक्यूमेंटेशन जनरेटर की तुलना

संदर्भ

• Wall, Larry; Christiansen, Tom; & Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 0-596-00027-8.
• Chapter 15, "Working with पॉड", in foy, brian d (2007). Mastering Perl. Sebastopol: O'Reilly Media. ISBN 0-596-52724-1.
• Section 5.2, "Embedding Documentation in Shell Scripts", in Albing, Carl; Vossen, JP; & Cameron Newham. (2007). bash Cookbook: Solutions and Examples for bash Users; O'Reilly & Associates. ISBN 0-596-52678-4.

बाहरी संबंध

• perlpod (documentation on पॉड for people writing documents in it)
• perlpodspec (documentation on पॉड for people writing parsers for it)
• The Perl manpages in raw पॉड format
• (PseudoPOD)
• The directory contains many modules with embedded पॉड formatting
• The Getopt::Euclid module parses input to a Perl script automatically based on पॉड tags
• The पॉड::Simple::Wiki converts पॉड into various Wiki formats
• The पॉड::मार्कडाउन converts पॉड into मार्कडाउन