Geekly Articles each Day

हम CMake के लिए सुविधाजनक दस्तावेज एकत्र करते हैं


सभी को नमस्कार!

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

यह कैसे काम करता है


पूरी प्रक्रिया एक अदृश्य और अल्पज्ञात तथ्य पर आधारित है: सीएमके के लिए प्रलेखन कई स्वरूपों में वितरित किया गया है: HTML, txt और DocBook v4.5। पहले दो के लिए आधार डॉकबुक प्रारूप में दस्तावेज़ीकरण है - यह सादे एक्सएमएल है जिसमें टैग का एक सख्त सेट है, जिसे, जैसा कि आपने अनुमान लगाया है, एक्सएलएसटी का उपयोग करके बिल्कुल किसी भी प्रतिनिधित्व में परिवर्तित किया जा सकता है। यह प्रारूप काफी लोकप्रिय है और मदद-दस्तावेजों के विभिन्न स्वरूपों में कन्वर्टर्स पहले से ही लिखे गए हैं, हमें बस उनमें से एक को लागू करने की आवश्यकता है। चूंकि CMake को क्रॉस-प्लेटफॉर्म के लिए डिज़ाइन किया गया है, इसलिए हम इसके लिए क्रॉस-प्लेटफॉर्म के लिए डॉक्यूमेंटेशन भी करेंगे। वेब मदद प्रारूप इसके लिए सबसे उपयुक्त है। जो लोग अपने स्वरूपों के साथ होमवर्क के रूप में प्रयोग कर सकते हैं।

सामग्री



पाठ के साथ, docbook-xsl पथ उस फ़ोल्डर को इंगित करेगा जहाँ आपने DocBook XSL टेम्पलेट के सेट को निकाला था।

DocBook webhelp टेम्पलेट


प्रत्येक डॉकबुक कन्वर्टर को अलग से विकसित किया जाता है, इसके संबंध में, उनमें से कुछ का समर्थन किया जाता है, दूसरों को लंबे समय तक अपडेट नहीं किया जाता है। सौभाग्य से, वेबहेल कनवर्टर काफी लोकप्रिय है और इसके उपयोग पर अच्छा प्रलेखन है, जो डॉक्बुक-एक्सएसएल / वेबहेल / डॉक्स फ़ोल्डर में पाया जा सकता है।

हमारी समस्या को हल करने के लिए प्रारंभिक कदम:

  1. डॉक्सबुक- xsl / webhelp / build.protties फ़ाइल में सैक्सन और Xerces के लिए पथ लिखें:
    # Modify the following so that they point to your local # copy of the jars indicated: # * Saxon 6.5 jar # * Xerces 2: xercesImpl.jar # * xml-commons: xml-apis.jar xslt-processor-classpath=d:/projects/CMake/doc/saxon6-5-5/saxon.jar xercesImpl.jar=d:/projects/CMake/doc/xerces-2_11_0/xercesImpl.jar xml-apis.jar=d:/projects/CMake/doc/xerces-2_11_0/xml-apis.jar

  2. डॉकबुक-xsl / webhelp फ़ोल्डर में निम्न कमांड चलाकर वेबहेल्प मॉड्यूल के डॉकबुक दस्तावेज़ के रूपांतरण की जाँच करें:
     ant webhelp -Doutput-dir=test-help

    यदि आपने सब कुछ सही ढंग से किया है, तो टीम का परिणाम कुछ इस तरह होना चाहिए:
    चींटी webhelp आउटपुट
     d: \ Projects \ CMake \ doc \ docbook-xsl-1.78.1 \ webhelp> ant webhelp -Doutput-dir = test-help
 Tools.jar का पता लगाने में असमर्थ।  C: \ Program Files \ Java \ jre7 \ lib \ tools.jar में इसे खोजने की उम्मीद है
 बिल्डफाइल: d: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-1.78.1 \ webhelp \ build.xml

 सत्यापित करें:

 साफ:

 हिस्सा:
     [mkdir] dir बनाया गया: d: \ Projects \ CMake \ doc \ docbook-xsl-1.78.1 \ webhelp \ test-help
      [xslt] d: \ Projects \ CMake \ docbook-xsl-1.78.1 \ webhelp \ docsrc \ readme.xml को d: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-1.78.1 \ webhelp \ test- परीक्षण में संसाधित करना help \ null1481456544
      [xslt] स्टाइलशीट लोड हो रहा है d: \ Projects \ CMake \ doc \ docbook-xsl-1.78.1 \ profiling \ profile.xsl
      [xslt] प्रसंस्करण d: \ प्रोजेक्ट \ CMake \ docbook-xsl-1.78.1 \ webhelp \ test-help \ null1481456544 से d: \ प्रोजेक्ट \ CMake \ docbook-xsl-1.78.1 \ webhelp \ test- परीक्षण help \ null884696268
      [xslt] स्टाइलशीट d लोड कर रहा है: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-1.78.1 \ webhelp \ xsl \ webhelp.xsl
      [xslt] भाषा: इं
      [xslt] अध्याय के लिए परीक्षण-सहायता / ch01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s02s01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s02.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s03.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s04.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch02s05.html लिखना
      [xslt] अध्याय के लिए परीक्षण-सहायता / ch02.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch03s01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch03s02s01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch03s02.html लिखना
      [xslt] अध्याय के लिए परीक्षण-सहायता / ch03.html लिखना
      [xslt] अध्याय के लिए परीक्षण-सहायता / ch04.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch05s01.html लिखना
      [xslt] अनुभाग के लिए परीक्षण-सहायता / ch05s02.html लिखना
      [xslt] अध्याय के लिए परीक्षण-सहायता / ch05.html लिखना
      [xslt] सूचकांक के लिए परीक्षण-सहायता / ix01.html लिखना
      [xslt] पुस्तक के लिए परीक्षण-सहायता / index.html लिखना
      [xslt] परीक्षण-सहायता / खोज / l10n.js लिखना
      [प्रतिलिपि] ९ ४ फाइलों की प्रतिलिपि बनाने के लिए: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-१.helhel.१ \ webhelp \ test-help
      [प्रतिलिपि] d: \ परियोजनाओं \ CMake \ doc \ docbook-xsl-१.helhel.१ \ webhelp \ test-help में 1 फ़ाइल की प्रतिलिपि बनाना

 सूचकांक:
      [प्रतिलिपि] d: \ Projects \ CMake \ doc \ docbook-xsl-१.helhel.१ \ webhelp \ test-help \ खोज के लिए १ फ़ाइल की प्रतिलिपि बनाना
      [प्रतिलिपि] d: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-१.ss.१ \ webhelp \ test-help \ सर्च के तहत १ खाली निर्देशिका को १ खाली निर्देशिका में कॉपी किया गया
      [प्रतिलिपि] d: \ प्रोजेक्ट \ CMake \ doc \ docbook-xsl-१.helhel.१ \ webhelp \ test-help \ खोज के लिए ४ फाइलों की नकल
      [गूंज] परीक्षण-सहायता में html फ़ाइलों को अनुक्रमणित करना
      [जावा] स्टेमिंग सक्षम किया गया
      [जावा] बनाई गई सूचकांक फाइलें परीक्षण-सहायता \ खोज में स्थित हैं
      [जावा] 828 मिलीसेकंड में सामग्री को अनुक्रमित किया

 webhelp:

 निर्माण सफलता है
 कुल समय: 35 सेकंड


    Docbook-xsl / webhelp / test-help फोल्डर में, webhelp मॉड्यूल के लिए जनरेट किया गया डॉक्यूमेंटेशन दिखाई देना चाहिए।

CMake प्रलेखन


चूंकि DocBook-> webhelp कन्वर्टर Apache Ant पर आधारित है, और कनवर्टर के डेवलपर्स ने इसकी कुछ उपयोगी विशेषताओं का उपयोग किया है, इसलिए हम DocBook से webhelp प्रारूप में कोई भी दस्तावेज़ बनाने के लिए एक सुविधाजनक वातावरण बना सकते हैं।

  1. एक कार्यशील फ़ोल्डर बनाएँ और cmake.docbook फ़ाइल की प्रतिलिपि बनाएँ, जो आमतौर पर स्थापित CMake फ़ोल्डर में स्थित होती है: doc / CMake-2.8 ।
  2. निम्न सामग्री के साथ कार्य फ़ोल्डर में build.xml फ़ाइल बनाएँ:
     <project default="help" name="cmake-doc"> <property name="input-xml" value="cmake.docbook"/> <import file="d:/projects/CMake/doc/docbook-xsl-1.78.1/webhelp/build.xml"/> </project>

    अपने वातावरण के अनुरूप फ़ाइल विशेषता में पथ समायोजित करें।
  3. हम पीढ़ी शुरू करते हैं:
     ant webhelp

    ... ... जाहिर है, हमें SUCCESSFUL नहीं, बल्कि नारकीय कॉल स्टैक के साथ एक त्रुटि मिलती है।
    छिपा हुआ पाठ
     d: \ प्रोजेक्ट \ CMake \ doc \ cmake_doc> चींटी webhelp
 Tools.jar का पता लगाने में असमर्थ।  C: \ Program Files \ Java \ jre7 \ lib \ tools.jar में इसे खोजने की उम्मीद है
 Buildfile: d: \ Projects \ CMake \ doc \ cmake_doc \ build.xml

 सत्यापित करें:

 साफ:
    [हटाएँ] निर्देशिका को हटाना d: \ प्रोजेक्ट \ CMake \ doc \ cmake_doc \ docs

 हिस्सा:
     [mkdir] dir बनाया गया: d: \ प्रोजेक्ट \ CMake \ doc \ cmake_doc \ _ डॉक्स
      [xslt] प्रसंस्करण d: \ परियोजनाओं \ CMake \ doc \ cmake_doc \ cmake.docbook को d: \ परियोजनाओं \ CMake \ doc \ cmake_doc \ docs \ null209688767678
      [xslt] स्टाइलशीट लोड हो रहा है d: \ Projects \ CMake \ doc \ docbook-xsl-1.78.1 \ profiling \ profile.xsl
      [xslt]: त्रुटि!  अधिक डीटीएम आईडी उपलब्ध नहीं हैं
      [xslt] d: \ Projects \ CMake \ doc \ cmake_doc \ cmake.docbook संसाधित करने में विफल

 निर्माण किया गया
 d: \ Projects \ CMake \ docbook-xsl-1.78.1 \ webhelp \ build.xml: 36: javax.xml.transform.TransformerException: com.sun.org .apache.xml.internal.dtm.DTMException: No अधिक DTM ID उपलब्ध हैं
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform (अज्ञात स्रोत) पर
         org.apache.tools.ant.taskdefs.optional.TraXLiaison.transform (TraXLiaison.java:195)
         org.apache.tools.ant.taskdefs.XSLTProcess.process (XSLTProcess.java:850)
         org.apache.tools.ant.taskdefs.XSLTProcess.execute (XSLTProcess.javaeps88)
         org.apache.tools.ant.UnognElement.execute (UnknownElement.java:292)
         sun.reflect.NativeMethodAccessorImpl.invoke0 (मूल विधि) पर
         sun.reflect.NativeMethodAccessorImpl.invoke (अज्ञात स्रोत) पर
         sun.reflect.DelegatingMethodAccessorImpl.invoke (अज्ञात स्रोत) पर
         java.lang.reflect.Method.invoke (अज्ञात स्रोत) पर
         org.apache.tools.ant.dispatch.DispatchUtils.execute (DispatchUtils.java:106)
         org.apache.tools.ant.Task.perform (टास्क.जवाप्स 48)
         org.apache.tools.ant.Target.execute (Target.java:435) पर
         org.apache.tools.ant.Target.performTasks (Target.java:456) पर
         org.apache.tools.ant.Project.executeSortedTargets (Project.java: 139393)
         org.apache.tools.ant.Project.executeTarget (Project.java:1364)
         org.apache.tools.ant.helper.DefaultExecutor.executeTargets (DefaultExecutor.java:41)
         org.apache.tools.ant.Project.executeTargets (Project.java:1248)
         org.apache.tools.ant.ain.runBuild (Main.java:851)
         org.apache.tools.ant.ain.startAnt (Main.java:235)
         org.apache.tools.ant.launch.Launcher.run (Launcher.java:280) पर
         org.apache.tools.ant.launch.Launcher.main (Launcher.java:109) पर
 इसके कारण: com.sun.org.apache.xml.internal.dtm.DTMException: अधिक DTM ID उपलब्ध नहीं हैं
         com.sun.org.apache.xml.internal.dtm.ref.DTMManagerDefault.addDTM (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.SAXImpl.getResultTreeFrag (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.DOMAdapter.getResultTreeFrag (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.MultiDOM.getResultTreeFrag (अज्ञात स्रोत) पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         profile.applyTemplates1 () पर
         प्रोफाइल पर .प्लेट $ डॉट $ 16 ()
         profile.applyTemplates () पर
         profile.transform () पर
         com.sun.org.apache.xalan.internal.xsltc.runtime.AbstractTranslet.transform (अज्ञात स्रोत) पर
         ... 22 और
 ---------
 com.sun.org.apache.xml.internal.dtm.DTMException: और अधिक DTM ID उपलब्ध नहीं हैं
         com.sun.org.apache.xml.internal.dtm.ref.DTMManagerDefault.addDTM (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.SAXImpl.getResultTreeFrag (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.DOMAdapter.getResultTreeFrag (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.dom.MultiDOM.getResultTreeFrag (अज्ञात स्रोत) पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         प्रोफ़ाइल पर। $ $ $ 1 ()
         profile.applyTemplates1 () पर
         profile.applyTemplates1 () पर
         प्रोफाइल पर .प्लेट $ डॉट $ 16 ()
         profile.applyTemplates () पर
         profile.transform () पर
         com.sun.org.apache.xalan.internal.xsltc.runtime.AbstractTranslet.transform (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform (अज्ञात स्रोत) पर
         com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform (अज्ञात स्रोत) पर
         org.apache.tools.ant.taskdefs.optional.TraXLiaison.transform (TraXLiaison.java:195)
         org.apache.tools.ant.taskdefs.XSLTProcess.process (XSLTProcess.java:850)
         org.apache.tools.ant.taskdefs.XSLTProcess.execute (XSLTProcess.javaeps88)
         org.apache.tools.ant.UnognElement.execute (UnknownElement.java:292)
         sun.reflect.NativeMethodAccessorImpl.invoke0 (मूल विधि) पर
         sun.reflect.NativeMethodAccessorImpl.invoke (अज्ञात स्रोत) पर
         sun.reflect.DelegatingMethodAccessorImpl.invoke (अज्ञात स्रोत) पर
         java.lang.reflect.Method.invoke (अज्ञात स्रोत) पर
         org.apache.tools.ant.dispatch.DispatchUtils.execute (DispatchUtils.java:106)
         org.apache.tools.ant.Task.perform (टास्क.जवाप्स 48)
         org.apache.tools.ant.Target.execute (Target.java:435) पर
         org.apache.tools.ant.Target.performTasks (Target.java:456) पर
         org.apache.tools.ant.Project.executeSortedTargets (Project.java: 139393)
         org.apache.tools.ant.Project.executeTarget (Project.java:1364)
         org.apache.tools.ant.helper.DefaultExecutor.executeTargets (DefaultExecutor.java:41)
         org.apache.tools.ant.Project.executeTargets (Project.java:1248)
         org.apache.tools.ant.ain.runBuild (Main.java:851)
         org.apache.tools.ant.ain.startAnt (Main.java:235)
         org.apache.tools.ant.launch.Launcher.run (Launcher.java:280) पर
         org.apache.tools.ant.launch.Launcher.main (Launcher.java:109) पर

 कुल समय: 16 सेकंड



WTF? // FIXME


एक विचार है कि त्रुटि का कारण सीएमके से एक बहुत बड़ी डॉकबुक फ़ाइल है जो कि वेबेलप कनवर्टर के परीक्षण के रूप में उपयोग की जाती है, क्योंकि यह रेखा अप्रत्यक्ष रूप से लॉग में इंगित करती है:
  [xslt] : Error! No more DTM IDs are available

एक समान त्रुटि को देखने के बाद, हम देखते हैं कि यह Xalan (Xerces द्वारा उपयोग किए गए XML पार्सर) को संदर्भित करता है और हल किया जा रहा है, लेकिन वास्तव में समस्याएं हैं। हम आवश्यक घटकों की प्रासंगिकता की जांच करते हैं - सब कुछ ठीक है। Cmake.docbook की जाँच करने के बाद, कोई भी सवाल नहीं उठा: बिल्कुल सही DocBook v4.5।
हम यह निष्कर्ष निकालते हैं कि Xalan + Xerces बड़ी फ़ाइलों पर सही ढंग से काम नहीं करती है, लेकिन हम समझते हैं कि दुनिया में XSLT कन्वर्टर्स एक विशाल गुच्छा हैं, और उनमें से अधिकांश समस्याओं के बिना बहुत बड़े संस्करणों के साथ काम करते हैं। तो, हम एक और XSLT ट्रांसफार्मर को जोड़ने की दिशा में खुदाई करते हैं।

डॉक्बुक-xsl / webhelp / build.xml फ़ाइल पर ध्यान देने के बाद, आप देख सकते हैं कि दो XSLT चरण हैं, लेकिन उनमें एक दिलचस्प अंतर है - उनमें से एक Xerces XSLT कनवर्टर का उपयोग करता है, और दूसरा सैक्सन का उपयोग करता है:

 <xslt in="${input-xml}" out="${xincluded-profiled.xml}" style="${ant.file.dir}/../profiling/profile.xsl" classpath="${xercesImpl.jar}"> <!--   xercesImpl.jar,     build.properties --> ... </xslt> <xslt in="${xincluded-profiled.xml}" out="${dummy.html}" style="${stylesheet-path}" scanincludeddirectories="false" classpath="${xslt-processor-classpath}"> <!--   Saxon.jar,     build.properties --> ... </xslt>

इस दृष्टिकोण के कारणों को समझना मुश्किल है, लेकिन शायद यह समस्या को हल करने का हमारा मौका है! हम पहले चरण में एक और XSLT कन्वर्टर लिखते हैं:

 <xslt in="${input-xml}" out="${xincluded-profiled.xml}" style="${ant.file.dir}/../profiling/profile.xsl" classpath="${xslt-processor-classpath}"> <!--     Saxon.jar --> ... </xslt>

हम पीढ़ी शुरू करते हैं और ... हमें लॉग के अंत में पोषित लाइनें मिलती हैं:

 ant webhelp ... BUILD SUCCESSFUL Total time: 2 minutes 33 seconds

पूरा होने पर, एक अलग प्रारूप में CMake पर सभी दस्तावेज़ डॉक्स फ़ोल्डर में दिखाई देंगे। आपको बस index.html खोलना होगा और आरंभ करना होगा।

निष्कर्ष


यदि वांछित है, तो प्रलेखन को एक वेब सर्वर या एक साझा गेंद पर अपलोड किया जा सकता है और पूरी टीम द्वारा निकाला जा सकता है।

मूल प्रारूप और वेब मदद की तुलना
मूल एक html पृष्ठ पर सभी कमांड का विवरण है (स्क्रॉल के आकार पर ध्यान दें)।


वेब मदद प्रारूप - वर्गों और उप-वर्गों की सूची के साथ एक सुविधाजनक पेड़।


हम निम्नलिखित लेखों में से एक में Win32, मैक ओएस एक्स, आईओएस और एंड्रॉइड प्लेटफॉर्म पर गेम डे में सीएमके के उपयोग को कवर करेंगे। वहां उनकी रूचि छत के ऊपर है।

Source: https://habr.com/ru/post/In193726/

More articles:


All Articles