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

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

डिज़ाइन

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

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

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

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

उपयोग

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

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

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

शुद्ध पॉड फ़ाइलों में आमतौर पर एक्सटेंशन होता है .pod, लेकिन पॉड का उपयोग ज्यादातर सीधे पर्ल में किया जाता है कोड, जो आम तौर पर उपयोग करता है .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

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

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

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

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

• एक एकल अपरकेस अक्षर, उसके बाद कम-से-चिह्न (<), स्वरूपित की जाने वाली सामग्री, और एक बड़े-से-अधिक चिह्न (>), उदाहरण के लिए। 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 Pod", 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 pod for people writing documents in it)
• perlpodspec (documentation on pod for people writing parsers for it)
• The Perl manpages in raw pod format
• (PseudoPOD)
• The directory contains many modules with embedded pod formatting
• The Getopt::Euclid module parses input to a Perl script automatically based on pod tags
• The Pod::Simple::Wiki converts pod into various Wiki formats
• The Pod::मार्कडाउन converts pod into मार्कडाउन