~noskcaj/ubuntu/utopic/gtk-doc/1.21 : revision 27

1

<?xml version="1.0" encoding="utf-8" standalone="no"?>

2

<?xml-stylesheet type="text/xml" href="params.xsl"?>

3

4

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "

5

http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

6

<!ENTITY FDL SYSTEM "fdl-appendix.xml">

7

<!ENTITY FDLlink "<link linkend='fdl'>included</link>">

8

]>

9

10

11

12

13

14

<abstract role="description"><para>GTK-Doc વપરાશની સૂચનાઓ સાથે ડેવલપરો માટે વપરાશકર્તા પુસ્તિકા.</para></abstract>

15

16

17

18

19

20

21

<email>chris@wilddev.net</email>

22

</address>

23

</affiliation>

24

</author>

25

26

27

28

29

30

<email>d-mueth@uchicago.edu</email>

31

</address>

32

</affiliation>

33

</author>

34

35

<firstname>સ્ટેફાન</firstname>

36

37

38

39

<email>ensonic@users.sf.net</email>

40

</address>

41

</affiliation>

42

</author>

43

</authorgroup>

44

45

<publishername>GTK-Doc પ્રોજેક્ટ</publishername>

46

<address><email>gtk-doc-list@gnome.org</email></address>

47

</publisher>

48

49

50

<holder>Dan Mueth and Chris Lyttle</holder>

51

</copyright>

52

53

54

<holder>Stefan Sauer (Kost)</holder>

55

</copyright>

56

57

<!-- translators: uncomment this:

58

59

60

<holder>ME-THE-TRANSLATOR (Latin translation)</holder>

61

</copyright>

62

-->

63

64

65

<para>Permission is granted to copy, distribute and/or modify this document under the terms of the <citetitle>GNU Free Documentation License</citetitle>, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is <link linkend="fdl">included</link>.</para>

66

<para>Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.</para>

67

</legalnotice>

68

69

70

<!--revision>

71

72

73

74

<revremark>development version, markdown support</revremark>

75

</revision-->

76

77

78

79

80

<revremark>bug fixes, speedups, markdown support</revremark>

81

</revision>

82

83

84

85

86

<revremark>urgent bug fix update</revremark>

87

</revision>

88

89

90

91

92

<revremark>bugfixes, layout improvements</revremark>

93

</revision>

94

95

96

97

98

<revremark>bug and regression fixes</revremark>

99

</revision>

100

101

102

<date>28 March 2010</date>

103

104

<revremark>bugfixes and performance improvements</revremark>

105

</revision>

106

107

108

<date>18 ડિસેમ્બર 2009</date>

109

110

<revremark>તૂટેલ ટારબોલ સુધારા</revremark>

111

</revision>

112

113

114

<date>18 ડિસેમ્બર 2009</date>

115

116

<revremark>નવા સાધન લક્ષણો અને ભૂલ સુધારાઓ</revremark>

117

</revision>

118

119

120

121

122

<revremark>GNOME doc-utils સ્થળાંતર</revremark>

123

</revision>

124

</revhistory>

125

126

</bookinfo>

127

128

129

130

131

<title>પરિચય</title>

132

133

<para>આ પ્રકરણ GTK-Doc ને રજૂ કરે છે અને તે શું છે અને તેને કેવી રીતે વપરાયેલ છે તેની ઝાંખી આપે છે.</para>

134

135

136

137

138

<para>GTK-Doc એ દસ્તાવેજ C કોડ માટે વપરાયેલ છે. તે લાઇબ્રેરીઓનાં સાર્વજનિક API નાં દસ્તાવેજ માટે વપરાયેલ છે, જેવું કે GTK+ અને GNOME લાઇબ્રેરીઓ. પરંતુ તે પણ દસ્તાવેજ કાર્યક્રમ કોડ માટે વપરાયેલ છે.</para>

139

</sect1>

140

141

142

143

144

<para>GTK-Doc એ વિશિષ્ટ રીતે માળખુ થયેલ ટિપ્પણી બ્લોકોમાં સ્ત્રોત ફાઇલોની અંદર સ્થિત થયેલ વિધેયોનાં દસ્તાવેજીકરણની મદદથી કામ કરે છે, અથવા દસ્તાવેજીકરણ ટેમ્પલેટ ફાઇલોમાં ઉમેરાયેલ છે કે જે GTK-Doc વાપરે છે (છતાંપણ નોંધો કે GTK-Doc એ પણ દસ્તાવેજ વિધેયો હશે કે જે શીર્ષક ફાઇલોમાં જાહેર થયેલ છે; તે સ્થિર વિધેયો માટે આઉટપુટ ઉત્પન્ન કરતુ નથી).</para>

145

146

<para>GTK-Doc એ perl સ્ક્રિપ્ટોની સંખ્યાને સમાવે છે, પ્રક્રિયામાં દરેક વિવિધ પગલું કરે છે.</para>

147

148

<para>ત્યાં પ્રક્રિયામાં મુખ્ય ૫ પગલાંઓ છે:</para>

149

150

151

152

153

<para><guilabel>દસ્તાવેજીકરણને લખી રહ્યા છે.</guilabel> લેખક એ દરેક વિધેયને, મેક્રો, યુનિયન વગેરે માટે દસ્તાવેજીકરણ સાથે સ્ત્રોત ફાઇલોમાં ભરે છે. (ઉત્પન્ન થયેલ ટેમ્પલેટ ફાઇલમાં ભૂતકાળની જાણકારી દાખલ થયેલ હતી, કે જે કોઇપણ રીતે અગ્રહણીય થયેલ નથી)</para>

154

</listitem>

155

156

157

<para>

158

<guilabel>Gathering information about the code.</guilabel>

159

160

<application>gtkdoc-scan</application> scans the header files of the

161

code looking for declarations of functions, macros, enums, structs, and unions.

162

It creates the file <filename><module>-decl-list.txt</filename> containg a list of the

163

declarations, placing them into sections according to which header file they

164

are in. On the first run this file is copied to <filename><module>-sections.txt</filename>.

165

The author can rearrange the sections, and the order of the

166

declarations within them, to produce the final desired order.

167

The second file it generates is <filename><module>-decl.txt</filename>.

168

This file contains the full declarations found by the scanner. If for

169

some reason one would like some symbols to show up in the docs, where

170

the full declaration cannot be found by the scanner or the declaration

171

should appear differently, one can place enties similar to the ones in

172

<filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.

173

174

<application>gtkdoc-scanobj</application> can also be used to dynamically query a library about

175

any GtkObject subclasses it exports. It saves information about each

176

object's position in the class hierarchy and about any GTK Args and Signals it

177

provides.

178

</para>

179

</listitem>

180

181

182

<para><guilabel>"template" ફાઇલોને ઉત્પન્ન કરી રહ્યા છે.</guilabel><application>gtkdoc-mktmpl</application> એ પહેલાં પગલામાં ભેગી થયેલ જાણકારીની મદદથી <filename class="directory">tmpl/</filename> ઉપડિરેક્ટરીમાં ફાઇલોની સંખ્યાને બનાવે છે. (નોંધો કે જે આ વારંવાર ચલાવી શકાય છે. તે ખાતરી કરવા માટે પ્રયત્ન કરશે કે જે દસ્તાવેજીકરણ હંમેશ માટે ગુમ થઇ જતો નથી.)</para>

183

<note>

184

<para>જ્યાં સુધી GTK-Doc 1.9 નાં ટેમ્પલેટને અવગણી શકાય છે ત્યાં સુધી. આપણે કોડમાં દસ્તાવેજીકરણ ને રાખવા માટે લોકોને પ્રોત્સાહિત કરો. <application>gtkdocize</application> એ હવે <option>--flavour no-tmpl</option> વિકલ્પને આધાર આપે છે કે જે makefile ને પસંદ કરે છે કે જે સંપૂર્ણપણે tmpl વપરાશને છોડી દે છે. જો તમે પોતાની જાતે tmpl માં ફાઇલને કદી બદલો નહિં તો, મહેરબાની કરીને dir ને દૂર કરો (દા.ત. આવૃત્તિ નિયંત્રણ સિસ્ટમ માંથી).</para>

185

</note>

186

</listitem>

187

188

189

<para>

190

<guilabel>Generating the SGML/XML and HTML/PDF.</guilabel>

191

192

<application>gtkdoc-mkdb</application> turns the template files into

193

SGML or XML files in the <filename class="directory">sgml/</filename>

194

or <filename class="directory">xml/</filename> subdirectory.

195

If the source code contains documentation on functions, using the

196

special comment blocks, it gets merged in here. If there are no tmpl files used

197

it only reads docs from sources and introspection data. We recommend

198

to use Docbook XML.

199

</para>

200

<para>

201

<application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML

202

files in the <filename class="directory">html/</filename> subdirectory.

203

Likewise <application>gtkdoc-mkpdf</application> turns the SGML/XML files into a PDF

204

document called <filename><package>.pdf</filename>.

205

</para>

206

<para><filename class="directory">sgml/</filename> અથવા <filename class="directory">xml/</filename> માં ફાઇલો અને <filename class="directory">html/</filename> ડિરેક્ટરીઓ એ હંમેશા ઉપલ લખાયેલ છે. એક એ સીધુ જ તેઓને કદી સુધારતુ હોવુ જોઇએ નહિં.</para>

207

</listitem>

208

209

210

<para>

211

<guilabel>Fixing up cross-references between documents.</guilabel>

212

213

After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any

214

cross-references between separate documents. For example, the GTK+

215

documentation contains many cross-references to types documented in the GLib manual.

216

217

When creating the source tarball for distribution, <application>gtkdoc-rebase</application>

218

turns all external links into web-links. When installing distributed (pregenerated) docs

219

the same application will try to turn links back to local links

220

(where those docs are installed).

221

</para>

222

</listitem>

223

</orderedlist>

224

225

</sect1>

226

227

228

<title>GTK-Doc ને મેળવી રહ્યા છે</title>

229

230

231

<title>જરૂરિયાતો</title>

232

233

<para><guilabel>DocBook DTD v3.0</guilabel> - આ DocBook SGML DTD છે. <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink></para>

234

<para><guilabel>Jade v1.1</guilabel> - આ વિવિધ માળખાઓમાં SGML ને રૂપાંતર કરવા માટે DSSSL પ્રોસેસર છે. <ulink url="http://www.jclark.com/jade" type="http">http://www.jclark.com/jade</ulink></para>

235

<para><guilabel>Modular DocBook Stylesheets</guilabel> આ DocBook ને HTML માં રૂપાંતરિત કરવા માટે DSSSL કોડ છે (અને થોડા બીજા બંધારણો). તે jade સાથે ભેગા વાપરેલ છે. મેં DSSSL કોડને કાર્યક્રમ કોડની યાદીઓ/ જાહેરાતોને રંગ આપવા માટે, અને ઉત્પન્ન થયેલ HTML માં વૈશ્ર્વિક પ્રતિનિર્દેશ સૂચિને આધાર આપવા માટે gtk-doc.dsl માં જરાક DSSSL કોડને વૈવિધ્યપૂર્ણ બનાવેલ છે. <ulink url="http://nwalsh.com/docbook/dsssl" type="http">http://nwalsh.com/docbook/dsssl</ulink></para>

236

<para><guilabel>docbook-to-man</guilabel> - જો તમે DocBook માંથી મુખ્ય પાનાંઓને બનાવવાનું ઇચ્છતા હોય તો, મેં થોડુ 'translation spec' ને વૈવિધ્યપૂર્ણ બનાવેલ છે, વિભાગનાં શીર્ષકનાં મોટા અક્ષર કરવા માટે અને પાનાંઓના ઊંચે 'GTK Library' શીર્ષકને ઉમેરો અને નીચે પૂનરાવર્તિત તારીખને ઉમેરો. ત્યાં <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink> પર આની કડી છે નોંધો: આ હજુ કામ કરતુ નથી.</para>

237

</sect2>

238

239

240

241

<para>ત્યાં મૂળભૂત સ્થાન નથી કે જ્યાં DocBook Modular Stylesheets એ સ્થાપિત થયેલ હોય.</para>

242

<para>GTK-Doc ની રૂપરેખાંકિત સ્ક્રિપ્ટ એ આ 3 ડિરેક્ટરીઓને આપમેળે શોધે છે:</para>

243

<para><filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (RedHat દ્દારા વપરાયેલ છે)</para>

244

<para><filename> /usr/lib/dsssl/stylesheets/docbook </filename> (Debian દ્દારા વપરાયેલ છે)</para>

245

<para><filename> /usr/share/sgml/docbkdsl </filename> (SuSE દ્દારા વપરાયેલ છે)</para>

246

<para>જો તમે ગમે ત્યાં સ્ટાઇલશીટો સ્થાપિત કરેલ હોય તો, તમે વિકલ્પની મદદથી GTK-Doc ને રૂપરેખાંકિત કરવા માટે જરૂ છે, <command> --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command></para>

247

</sect2>

248

249

</sect1>

250

251

<!-- not realy worth a section

252

253

254

255

<para>

256

(What things GTK-Doc should, and shouldn't, be used for.)

257

(- ???)

258

(- non C-based projects)

259

(+ Tutorials)

260

</para>

261

262

</sect1>

263

-->

264

265

266

267

268

<para>(FIXME)</para>

269

270

<para>(ઇતિહાસ, લેખકો, વેબ પાનાંઓ, લાઇસન્સ, ભવિષ્યનાં પ્લાનો, સરખી સિસ્ટમો સાથે સરખામણી.)</para>

271

272

</sect1>

273

274

275

276

277

<para>(FIXME)</para>

278

279

<para>

280

(who it is meant for, where you can get it, license)

281

</para>

282

283

</sect1>

284

285

</chapter>

286

287

288

<title>તમારા પ્રોજેક્ટને સુયોજિત કરી રહ્યા છે</title>

289

290

<para>

291

The next sections describe what steps to perform to integrate GTK-Doc into

292

your project. Theses sections assume we work on a project called 'meep'.

293

This project contains a library called 'libmeep' and

294

an end-user app called 'meeper'. We also assume you will be using autoconf

295

and automake. In addition section <link linkend="plain_makefiles">plain

296

makefiles or other build systems</link> will describe the basics needed to

297

work in a different build setup.

298

</para>

299

300

301

<title>સ્કેલેટન દસ્તાવેજીકરણને સુયોજિત કરી રહ્યા છે</title>

302

303

<para>

304

Under your top-level project directory create folders called docs/reference

305

(this way you can also have docs/help for end-user documentation).

306

It is recommended to create another subdirectory with the name of the doc-package.

307

For packages with just one library this step is not necessary.

308

</para>

309

310

<para>

311

This can then look as shown below:

312

<example><title>ઉદાહરણ ડિરેક્ટરી બંધારણ</title>

313

314

<![CDATA[

315

meep/

316

docs/

317

reference/

318

libmeep/

319

meeper/

320

src/

321

libmeep/

322

meeper/

323

]]>

324

</programlisting>

325

</example>

326

</para>

327

</sect1>

328

329

330

<title>autoconf સાથે એકત્રિકરણ</title>

331

332

<para>ઘણું સરળ છે! ફક્ત તમારી <filename>configure.ac</filename> સ્ક્રિપ્ટમાં એક વાક્ય ને ઉમેરો.</para>

333

334

<para>

335

<example><title>autoconf સાથે એકત્રિકરણ</title>

336

337

<![CDATA[

338

# check for gtk-doc

339

GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

340

]]>

341

</programlisting>

342

</example>

343

</para>

344

345

<para>

346

This will require all developers to have gtk-doc installed. If it is

347

okay for your project to have optional api-doc build setup, you can

348

solve this as below. Keep it as is, as gtkdocize is looking for

349

<function>GTK_DOC_CHECK</function> at the start of a line.

350

<example><title>Keep gtk-doc optional</title>

351

352

<![CDATA[

353

# check for gtk-doc

354

m4_ifdef([GTK_DOC_CHECK], [

355

GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

356

],[

357

AM_CONDITIONAL([ENABLE_GTK_DOC], false)

358

])

359

]]>

360

</programlisting>

361

</example>

362

</para>

363

364

<para>પહેલી દલીલ રૂપરેખાંકિત સમયે gtkdocversion માટે ચકાસવા વપરાયેલ છે. બીજી, વૈકલ્પિક દલીલ એ <application>gtkdocize</application> દ્દારા વપરાયેલ છે. <symbol>GTK_DOC_CHECK</symbol> મેક્રો પણ ઘણીબધા રૂપરેખાંકિત ફેરબદલોને ઉમેરે છે:</para>

365

366

<listitem><para>--with-html-dir=PATH : સ્થાપિત થયેલ દસ્તાવેજોનો પાથ</para></listitem>

367

<listitem><para>--enable-gtk-doc : દસ્તાવેજીકરણ ને બિલ્ડ કરવા માટે gtk-doc ને વાપરો [default=no]</para></listitem>

368

<listitem><para>--enable-gtk-doc-html : html બંધારણમાં દસ્તાવેજીકરણ બિલ્ડ કરો [default=yes]</para></listitem>

369

<listitem><para>--enable-gtk-doc-pdf : pdf બંધારણમાં દસ્તાવેજીકરણને બિલ્ડ કરો [default=no]</para></listitem>

370

</orderedlist>

371

372

373

<para>GTK-Doc એ મૂળભૂત રીતે નિષ્ક્રિય થયેલ છે! આગળનાં <filename>configure</filename> ને ચલાવવા માટે <option>'--enable-gtk-doc'</option> ને પસાર કરવાનું યાદ રાખો. નહિં તો પહેલીથી ઉત્પન્ન થયેલ દસ્તાવેજીકરણ સ્થાપિત થયેલ છે (કે જે વપરાશકર્તાઓ માટેનો અર્થ બને છે પરંતુ ડેવલપરો માટે નહિં).</para>

374

</important>

375

376

<para>આગળ વધારે તે અગ્રહણીય થયેલ છે કે જે તમારી પાસે તમારી <filename>configure.ac</filename> સ્ક્રિપ્ટની અંદર નીચેનું વાક્ય છે. આ તમારા પ્રોજેક્ટમાં <function>GTK_DOC_CHECK</function> માટે મેક્રો વ્યાખ્યાને આપમેળે નકલ કરવા માટે પરવાનગી આપે છે.</para>

377

378

<para>

379

<example><title>gtkdocize માટે તૈયારી</title>

380

381

<![CDATA[

382

AC_CONFIG_MACRO_DIR(m4)

383

]]>

384

</programlisting>

385

</example>

386

</para>

387

</sect1>

388

389

390

<title>automake સાથે એકત્રિકરણ</title>

391

392

<para>તમારા પ્રોજેક્ટની API દસ્તાવેજીકરણ ડિરેક્ટરી ( <filename class="directory">./docs/reference/<package></filename>) માં gtkdoc-સ્ત્રોતોની ઉપડિરેક્ટરીઓનાં ઉદાહરણો માંથી <filename>Makefile.am</filename> ની પહેલી નકલ કરો. જો તમારી પાસે દરેક એક માટે ઘણાબધા ફરી આવતા દસ્તાવેજ-પેકેજો છે.</para>

393

394

<para>

395

The next step is to edit the settings inside the <filename>Makefile.am</filename>.

396

All the settings have a comment above that describes their purpose.

397

Most settings are extra flags passed to the respective tools. Every tool

398

has a variable of the form <option><TOOLNAME>_OPTIONS</option>.

399

All the tools support <option>--help</option> to list the supported

400

parameters.

401

</para>

402

403

404

405

<para>

406

You may also want to enable GTK-Doc for the distcheck make target. Just

407

add the one line shown in the next example to your top-level

408

<filename>Makefile.am</filename>:

409

</para>

410

411

<para>

412

<example><title>distcheck ને બનાવવા દરમ્યાન GTK-Doc ને સક્રિય કરો</title>

413

414

<![CDATA[

415

DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

416

]]>

417

</programlisting>

418

</example>

419

</para>

420

421

</sect1>

422

423

424

<title>autogen સાથે એકત્રિકરણ</title>

425

426

<para>મોટાભાગનાં પ્રોજેક્ટો પાસે આવૃત્તિ નિયંત્રણ સિસ્ટમ (જેવી કે cvs/svn/git) માંથી ચેકઆઉટ પછી ઇન્ફ્રાસ્ટ્રક્ચરને બિલ્ડ કરવાનું સુયોજિત કરવા માટે <filename>autogen.sh</filename> સ્ક્રિપ્ટ હશે. GTK-Doc એ સાધન <application>gtkdocize</application> તરીકે કહેવાતા સાધન સાથે આવે છે કે જે આવી સ્ક્રિપ્ટમાં વાપરી શકાય છે. તે autoheader, automake અથવા autoconf પહેલાં ચાલવુ જોઇએ.</para>

427

428

<para>

429

<example><title>autogen.sh માંથી gtkdocize ને ચલાવી રહ્યા છે</title>

430

431

<![CDATA[

432

gtkdocize || exit 1

433

]]>

434

</programlisting>

435

</example>

436

</para>

437

438

<para>

439

When running <application>gtkdocize</application> it copies

440

<filename>gtk-doc.make</filename> to your project root (or any directory

441

specified by the <option>--docdir</option> option).

442

It also checks you configure script for the <function>GTK_DOC_CHECK</function>

443

invocation. This macro can be used to pass extra parameters to

444

<application>gtkdocize</application>.

445

</para>

446

447

<para>

448

Historically GTK-Doc was generating template files where developers entered the docs.

449

This turned out to be not so good (e.g. the need for having generated

450

files under version control).

451

Since GTK-Doc 1.9 the tools can get all the information from source comments

452

and thus the templates can be avoided. We encourage people to keep

453

documentation in the code. <application>gtkdocize</application> supports now

454

a <option>--flavour no-tmpl</option> option that chooses a makefile that skips

455

tmpl usage totally. Besides adding the option directly to the command

456

invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>

457

or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.

458

If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,

459

please remove the dir (e.g. from version control system).

460

</para>

461

</sect1>

462

463

464

<title>દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે</title>

465

466

<para>પહેલાનાં પગલાઓ પછી બિલ્ડ ને ચલાવવા માટે સમય થઇ ગયો છે. પહેલાં આપણે <filename>autogen.sh</filename> પુન:ચલાવવાની જરૂર છે. નહિં તો પછીથી આ વિકલ્પ સાથે <filename>configure</filename> ને જાતે જ ચલાવો.</para>

467

<para>

468

The first make run generates several additional files in the doc-dirs.

469

The important ones are:

470

<filename><package>.types</filename>,

471

<filename><package>-docs.xml</filename> (in the past .sgml),

472

<filename><package>-sections.txt</filename>.

473

</para>

474

<para>

475

<example><title>દસ્તાવેજ બિલ્ડને ચલાવી રહ્યા છે</title>

476

477

<![CDATA[

478

./autogen.sh --enable-gtk-doc

479

make

480

]]>

481

</programlisting>

482

</example>

483

</para>

484

<para>હવે તમે <filename>docs/reference/<package>/index.html</filename> માટે તમારા બ્રાઉઝર પર આંગળી ચીંધી શકો છો. હાં, તે થોડુ હજુ નિરાશ કરે તેવુ છે. પરંતુ આગળનામ વિષય માટે આપણે તને કહીએ છે કે જીદંગી સાથે પાનાંઓને કેવી રીતે ભરવા તે દરમ્યાન થોડા સમય માટે અટકી જાય છે</para>

485

</sect1>

486

487

488

<title>આવૃત્તિ નિયંત્રણ સિસ્ટમો સાથે એકત્રિકરણ</title>

489

490

<para>

491

As a rule of the thumb, it's those files you edit, that should go under

492

version control. For typical projects it's these files:

493

<filename><package>.types</filename>,

494

<filename><package>-docs..xml</filename> (in the past .sgml),

495

<filename><package>-sections.txt</filename>,

496

<filename>Makefile.am</filename>

497

</para>

498

</sect1>

499

500

501

<title>Integration with plain makefiles or other build systems</title>

502

503

<para>

504

In the case one does not want to use automake and therfore

505

<filename>gtk-doc.mak</filename> one will need to call the gtkdoc tools

506

in the right order in own makefiles (or other build tools).

507

</para>

508

509

<para>

510

<example><title>Documentation build steps</title>

511

512

<![CDATA[

513

DOC_MODULE=meep

514

// sources have changed

515

gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...

516

gtkdoc-scangobj --module=$(DOC_MODULE)

517

gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml

518

// xml files have changed

519

mkdir html

520

cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml

521

gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

522

]]>

523

</programlisting>

524

</example>

525

</para>

526

527

<para>

528

One will need to look at the <filename>Makefile.am</filename> and

529

<filename>gtk-doc.mak</filename> to pick the extra options needed.

530

</para>

531

</sect1>

532

533

</chapter>

534

535

536

<title>કોડને દસ્તાવેજ કરી રહ્યા છે</title>

537

538

<para>

539

GTK-Doc uses source code comment with a special syntax for code documentation.

540

Further it retrieves information about your project structure from other

541

sources. During the next section you will find all information about the

542

syntax of the comments.

543

</para>

544

545

<note>

546

<title>દસ્તાવેજીકરણ નિયુક્તિ</title>

547

<para>

548

In the past most documentation had to be filled into files residing

549

inside the <filename>tmpl</filename> directory. This has the

550

disadvantages that the information is often not updated and also that

551

the file tend to cause conflicts with version control systems.

552

</para>

553

<para>

554

The avoid the aforementioned problems we suggest putting the

555

documentation inside the sources. This manual will only describe this

556

way of documenting code.

557

</para>

558

</note>

559

560

<para>

561

The scanner can handle the majority of c headers fine. In the case of

562

receiving warnings from the scanner that look like a special case, one can

563

hint GTK-Doc to skip over them.

564

565

566

<![CDATA[

567

#ifndef __GTK_DOC_IGNORE__

568

/* unparseable code here */

569

#endif

570

]]>

571

</programlisting>

572

</example>

573

</para>

574

575

576

577

578

<title>દસ્તાવેજીકરણ ટિપ્પણીઓ</title>

579

580

<para>ઘણીબધા વાક્યની ટિપ્પણીઓ કે જે વધારાનાં '*' ચિહ્ન દસ્તાવેજીકરણ બ્લોક સાથે શરૂ થાય છે કે જે GTK-Doc સાધનો દ્દારા પ્રક્રિયા થયેલ હશે. <example><title>GTK-Doc ટિપ્પણી બ્લોક</title>

581

582

<![CDATA[

583

/**

584

* identifier:

585

* documentation ...

586

*/

587

]]>

588

</programlisting>

589

</example></para>

590

591

<para>

592

The 'identifier' is one line with the name of the item the comment is

593

related to. The syntax differs a little depending on the item.

594

(TODO add table showing identifiers)

595

</para>

596

597

<para>

598

The 'documentation' block is also different for each symbol type. Symbol

599

types that get parameters such as functions or macros have the parameter

600

description first followed by a blank line (just a '*').

601

Afterwards follows the detailed description. All lines (outside program-

602

listings and CDATA sections) just containing a ' *' (blank-asterisk) are

603

converted to paragraph breaks.

604

If you don't want a paragraph break, change that into ' * '

605

(blank-asterisk-blank-blank).

606

</para>

607

608

<tip>

609

<para>

610

When documenting code, describe two apsects:

611

612

613

<para>

614

What it is: The name for a class or function can sometimes

615

be misleading for people coming from a different background.

616

</para>

617

</listitem>

618

619

<para>

620

What it does: Tell about common uses. Put it in releation

621

with the other API.

622

</para>

623

</listitem>

624

</itemizedlist>

625

</para>

626

</tip>

627

628

<para>

629

One advantage of hyper-text over plain-text is the ability to have links

630

in the document. Writing the correct markup for a link can be tedious

631

though. GTK-Doc comes to help by providing several useful abbreviations.

632

633

634

<para>વિધેયો અથવા મેક્રોનો સંદર્ભ લેવા માટે function() ને વાપરો કે જે દલીલોને લે છે.</para>

635

</listitem>

636

637

<para>પરિમાણોનો સંદર્ભ લેવા માટે @param ને વાપરો. બીજા વિધેયોનાં પરિમાણો માટે જ્યારે સંદર્ભ કરી રહ્યા હોય ત્યારે આને પણ વાપરો, વર્ણવવા માટે એકને સંબંધિત છે.</para>

638

</listitem>

639

640

<para>કૉન્સ્ટન્ટ નો સંદર્ભ લેવા માટે %constant ને વાપરો, દા.ત. %G_TRAVERSE_LEAFS.</para>

641

</listitem>

642

643

<para>સંકેતનાં બીજા પ્રકારોનો સંદર્ભ લેવા માટે #symbol ને વાપરો, દા.ત. structs અને enums અને macros કે જે દલીલો લેતુ નથી.</para>

644

</listitem>

645

646

<para>#Object ને વાપરો::GObject સંકેતનો સંદર્ભ લેવા માટે સંકેત</para>

647

</listitem>

648

649

<para>#Object ને વાપરો:GObject ગુણધર્મનો સંદર્ભ લેવા માટે ગુણધર્મ</para>

650

</listitem>

651

652

<para>બંધારણની અંદર ક્ષેત્રનો સંદર્ભ લેવા માટે #Struct.field ને વાપરો.</para>

653

</listitem>

654

</itemizedlist>

655

</para>

656

657

<tip>

658

<para>જો તમારે તેઓને બદલ્યા વગર GTK-Doc વગર તમારાં દસ્તાવેજીકરણમાં વિશિષ્ટ અક્ષરો '<', '>', '()', '@', '%', or '#' ને વાપરવાનું ઇચ્છતા હોય તો તમે XML વસ્તુઓ "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" અને "&num;" ને વાપરી શકો છો અથવા બેકસ્લેશ '\' સાથે તેઓમાંથી બહાર નીકળી જાઓ.</para>

659

</tip>

660

661

<para>

662

DocBook can do more than just links. One can also have lists, tables and

663

examples. To enable the usage of docbook SGML/XML tags inside

664

doc-comments you need to have <option>--xml-mode</option> or

665

<option>--sgml-mode</option> in the variable

666

<symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.

667

</para>

668

669

<para>

670

Since GTK-Doc-1.18 the tool supports a subset or the

671

<ulink url="http://daringfireball.net/projects/markdown/">markdown language</ulink>.

672

One can use it for sub-headings and simple itemized lists. On older

673

GTK-Doc versions the content will be rendered as it (the list items will

674

appear in one line separated by dashes).

675

<example><title>GTK-Doc comment block using markdown</title>

676

677

<![CDATA[

678

/**

679

* identifier:

680

*

681

* documentation ...

682

*

683

* # Sub heading #

684

*

685

* more documentation:

686

* - list item 1

687

* - list item 2

688

*

689

* Even more docs.

690

*/

691

]]>

692

</programlisting>

693

</example>

694

</para>

695

696

<tip>

697

<para>પહેલાનાં GTK-Doc માં પહેલેથી જણાવેલ પ્રમાણે સાર્વજનિક API દસ્તાવેજીકરણ માટે છે. છતાં એક એ સ્થિર સંકેતો માટે દસ્તાવેજીકરણ ને લખી શકતુ નથી. તેમ છતાં તે પેલાં સંકેતો પર ટિપ્પણી કરવા માટે સારુ છે. આ તમારાં કોડને સમજવા માટે બીજાને મદદ કરે છે. માટે આપણે સામાન્ય ટિપ્પણીઓની મદદથી આ ટિપ્પણી એ અગ્રહણીય કરેલ છે (પહેલાં વાક્યમાં બીજા '*' વગર). જો પછી વિધેયને સાર્વજનિક બનાવવાની જરૂર છે, ટિપ્પણી બ્લોકમાં બીજા '*' ઉમેરવા માટે બધાને કરવાની જરૂર છે અને ફાઇલ વિભાગોની અંદર જમણી જગ્યા પર સંકેત નામને દાખલ કરો.</para>

698

</tip>

699

</sect1>

700

701

702

<title>વિભાગોનું દસ્તાવેજ કરી રહ્યા છે</title>

703

704

<para>દસ્તાવેજીકરણનો દરેક વિભાગ એ એર વર્ગ અથવા મોડ્યુલ વિશે જાણકારીને સમાવે છે. એક ઘટક એ વિભાગ બ્લોક લખી શકે છે તે રજૂ કરવા માટે. ટૂંકુ વર્ણન એ સમાવિષ્ટોનાં કોષ્ટકની અંદર પણ વપરાયેલ છે. બધી @fields વૈકલ્પિક છે.</para>

705

706

<para>

707

<example><title>વિભાગ ટિપ્પણી બ્લોક</title>

708

709

<![CDATA[

710

/**

711

* SECTION:meepapp

712

* @short_description: the application class

713

* @title: Meep application

714

* @section_id:

715

* @see_also: #MeepSettings

716

* @stability: Stable

717

* @include: meep/app.h

718

* @image: application.png

719

*

720

* The application class handles ...

721

*/

722

]]>

723

</programlisting>

724

</example>

725

</para>

726

727

728

729

<term>SECTION:<name></term>

730

731

<para>

732

The name links the section documentation to the respective part in

733

the <filename><package>-sections.txt</filename> file. The

734

name give here should match the <FILE> tag in the

735

<filename><package>-sections.txt</filename> file.

736

</para>

737

</listitem>

738

</varlistentry>

739

740

<term>@shortdescription (_d)</term>

741

742

<para>વિભાગનું એક વાક્યનું વર્ણન, કે જે પછી TOC માં અને વિભાગ પાનાંની ટોચે કડીઓ પછી દેખાશે.</para>

743

</listitem>

744

</varlistentry>

745

746

<term>@title</term>

747

748

<para>વિભાગનું શીર્ષક એ SECTION રજૂઆતમાંથી <name> માટે મૂળભૂત કરેલ છે. તે @title ક્ષેત્ર સાથે અવગણી શકાય છે.</para>

749

</listitem>

750

</varlistentry>

751

752

<term>@sectionid (_i)</term>

753

754

<para>

755

Overrides the use of title as a section identifier. For GObjects

756

the <title> is used as a section_id and for other sections

757

it is <MODULE>-<title>.

758

</para>

759

</listitem>

760

</varlistentry>

761

762

<term>@seealso (_a)</term>

763

764

<para>

765

A list of symbols that are related to this section.

766

</para>

767

</listitem>

768

</varlistentry>

769

770

<term>@stability</term>

771

772

<para>

773

A informal description of the stability level this API has.

774

We recommend the use of one of these terms:

775

776

777

<para>

778

Stable

779

- The intention of a Stable interface is to enable arbitrary

780

third parties to develop applications to these interfaces,

781

release them, and have confidence that they will run on all

782

minor releases of the product (after the one in which the

783

interface was introduced, and within the same major release).

784

Even at a major release, incompatible changes are expected

785

to be rare, and to have strong justifications.

786

</para>

787

</listitem>

788

789

<para>

790

Unstable

791

- Unstable interfaces are experimental or transitional.

792

They are typically used to give outside developers early

793

access to new or rapidly changing technology, or to provide

794

an interim solution to a problem where a more general

795

solution is anticipated.

796

No claims are made about either source or binary

797

compatibility from one minor release to the next.

798

</para>

799

</listitem>

800

801

<para>ખાનગી - ઇન્ટપફેસ કે જે GNOME સ્ટેક પોતામાં વાપરી શકાય છે, પરંતુ અંતિમ વપરાશકર્તાઓ માટે દસ્તાવેજ થયેલ નથી. જેવા કે વિધેયો એ સ્પષ્ટ થયેલ અને દસ્તાવેજ પ્રમાણે પમ વાપરવુ જોઇએ.</para>

802

</listitem>

803

804

<para>આંતરિક - ઇન્ટરફેસ કે જે મોડ્યુલ માટે આંતરિક છે અને અંતિમ-વપરાશકર્તાનાં દસ્તાવેજીકરણની જરૂર નથી. વિધેયો કે જે દસ્તાવેજ થયેલ નથી તે આંતરિક કરવા માટે ધારેલ છે.</para>

805

</listitem>

806

</itemizedlist>

807

</para>

808

</listitem>

809

</varlistentry>

810

811

<term>@include</term>

812

813

<para>

814

The <literal>#include</literal> files to show in the section

815

synopsis (a comma separated list), overriding the global

816

value from the <link linkend="metafiles_sections">section

817

file</link> or command line. This item is optional.

818

</para>

819

</listitem>

820

</varlistentry>

821

822

<term>@image</term>

823

824

<para>

825

The image to display at the top of the reference page for this

826

section. This will often be some sort of a diagram to illustrate

827

the visual appearance of a class or a diagram of its relationship

828

to other classes. This item is optional.

829

</para>

830

</listitem>

831

</varlistentry>

832

</variablelist>

833

834

<tip>

835

<para>

836

To avoid unnecessary recompilation after doc-changes put the section

837

docs into the c-source where possible.

838

</para>

839

</tip>

840

841

</sect1>

842

843

844

<title>સંકેતોનું દસ્તાવેજ કરી રહ્યા છે</title>

845

846

<para>

847

Each symbol (function, macro, struct, enum, signal and property) is

848

documented in a separate block. The block is best placed close to the

849

definition of the symbols so that it is easy to keep them in sync.

850

Thus functions are usually documented in the c-source and macros,

851

structs and enums in the header file.

852

</para>

853

854

<sect2><title>સામાન્ય ટેગ</title>

855

856

<para>

857

You can add versioning information to all documentation elements to tell

858

when an api was introduced, or when it was deprecated.

859

</para>

860

861

<variablelist><title>Versioning Tags</title>

862

863

864

<para>વર્ણન જ્યાં સુધી API કોડનું કઇ આવૃત્તિ ઉપલ્બધ છે.</para>

865

</listitem>

866

</varlistentry>

867

<varlistentry><term>અપ્રચલિત થયેલ:</term>

868

869

<para>ફકરાને સૂચિત કરી રહ્યા છે કે જે આ વિધેયને વધારે વાપરવુ જોઇએ નહિં. વર્ણનએ નવા API માટે વાંચનારને ધ્યાન લેવુ જોઇએ.</para>

870

</listitem>

871

</varlistentry>

872

</variablelist>

873

874

<para>(FIXME : સ્થિરતા જાણકારી)</para>

875

876

<example><title>સામાન્ય ટેગ</title>

877

878

<![CDATA[

879

/**

880

* foo_get_bar:

881

* @foo: some foo

882

*

883

* Retrieves @foo's bar.

884

*

885

* Returns: @foo's bar

886

*

887

* Since: 2.6

888

* Deprecated: 2.12: Use foo_baz_get_bar() instead.

889

**/

890

Bar *

891

foo_get_bar(Foo *foo)

892

{

893

...

894

]]>

895

</programlisting>

896

</example>

897

</sect2>

898

899

<sect2><title>વિધેય ટિપ્પણી બ્લોક</title>

900

901

<para>મહેરબાની કરીને યાદ રાખો: <itemizedlist>

902

903

<para>

904

Document whether returned objects, lists, strings, etc, should be

905

freed/unrefed/released.

906

</para>

907

</listitem>

908

909

<para>દસ્તાવેજ ક્યાંતો પરિમાણો એ NULL હોઇ શકે છે, અને શું થશે જો તેઓ છે તો.</para>

910

</listitem>

911

912

<para>

913

Mention interesting pre-conditions and post-conditions where appropriate.

914

</para>

915

</listitem>

916

</itemizedlist></para>

917

918

<para>Gtk-doc એ '_' સાથે શરૂ થતા બધા સંકેતો (મેક્રો, વિધેયો) ને ખાનગી ધારે છે. તેઓ સ્થિર વિધેયો જેવું વર્ણતૂક કરે છે.</para>

919

920

<para>

921

922

Also, take a look at gobject introspection annotation tags:

923

http://live.gnome.org/GObjectIntrospection/Annotations

924

</para>

925

926

<example><title>વિધેય ટિપ્પણી બ્લોક</title>

927

928

<![CDATA[

929

/**

930

* function_name:

931

* @par1: description of parameter 1. These can extend over more than

932

* one line.

933

* @par2: description of parameter 2

934

* @...: a %NULL-terminated list of bars

935

*

936

* The function description goes here. You can use @par1 to refer to parameters

937

* so that they are highlighted in the output. You can also use %constant

938

* for constants, function_name2() for functions and #GtkWidget for links to

939

* other declarations (which may be documented elsewhere).

940

*

941

* Returns: an integer.

942

*

943

* Since: 2.2

944

* Deprecated: 2.18: Use other_function() instead.

945

*/

946

]]>

947

</programlisting>

948

</example>

949

950

<variablelist><title>વિધેય ટૅગો</title>

951

952

953

<para>ફકરો પાછુ મળેલ પરિણામને વર્ણવી રહ્યા છે.</para>

954

</listitem>

955

</varlistentry>

956

957

958

<para>

959

In case the function has variadic arguments, you should use this

960

tag (@Varargs: does also work for historic reasons).

961

</para>

962

</listitem>

963

</varlistentry>

964

</variablelist>

965

966

</sect2>

967

968

<sect2><title>ગુણધર્મ ટિપ્પણી બ્લોક</title>

969

970

<example><title>ગુણધર્મ ટિપ્પણી બ્લોક</title>

971

972

<![CDATA[

973

/**

974

* SomeWidget:some-property:

975

*

976

* Here you can document a property.

977

*/

978

g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

979

]]>

980

</programlisting>

981

</example>

982

983

</sect2>

984

985

<sect2><title>સંકેત ટિપ્પણા બ્લોક</title>

986

987

<para>મહેરબાની કરીને યાદ રાખો: <itemizedlist>

988

989

<para>

990

Document when the signal is emitted and whether it is emitted before

991

or after other signals.

992

</para>

993

</listitem>

994

995

<para>

996

Document what an application might do in the signal handler.

997

</para>

998

</listitem>

999

</itemizedlist></para>

1000

1001

<example><title>સંકેત ટિપ્પણા બ્લોક</title>

1002

1003

<![CDATA[

1004

/**

1005

* FooWidget::foobarized:

1006

* @widget: the widget that received the signal

1007

* @foo: some foo

1008

* @bar: some bar

1009

*

1010

* The ::foobarized signal is emitted each time someone tries to foobarize @widget.

1011

*/

1012

foo_signals[FOOBARIZE] =

1013

g_signal_new ("foobarize",

1014

...

1015

]]>

1016

</programlisting>

1017

</example>

1018

1019

</sect2>

1020

1021

<sect2><title>Struct ટિપ્પણી બ્લોક</title>

1022

<example><title>Struct ટિપ્પણી બ્લોક</title>

1023

1024

<![CDATA[

1025

/**

1026

* FooWidget:

1027

* @bar: some #gboolean

1028

*

1029

* This is the best widget, ever.

1030

*/

1031

typedef struct _FooWidget {

1032

/*< private >*/

1033

GtkWidget parent;

1034

1035

/*< public >*/

1036

gboolean bar;

1037

} FooWidget;

1038

]]>

1039

</programlisting>

1040

</example>

1041

1042

<para>

1043

Use <code>/*< private >*/</code> before the private struct fields

1044

you want to hide. Use <code>/*< public >*/</code> for the reverse

1045

behaviour.

1046

</para>

1047

1048

<para>

1049

Struct comment blocks can also be used for GObjects and GObjectClasses.

1050

It is usualy a good idea to add a comment blco for a class, if it has

1051

vmethods (as this is how they can be documented). For the GObject

1052

itself one can use the related section docs, having a separate block

1053

for the instance struct would be useful if the instance has public

1054

fields. One disadvantage here is that this creates two index entries

1055

of the same name (the structure and the section).

1056

</para>

1057

1058

</sect2>

1059

1060

1061

1062

1063

<![CDATA[

1064

/**

1065

* Something:

1066

* @SOMETHING_FOO: something foo

1067

* @SOMETHING_BAR: something bar

1068

*

1069

* Enum values used for the thing, to specify the thing.

1070

*

1071

**/

1072

typedef enum {

1073

SOMETHING_FOO,

1074

SOMETHING_BAR,

1075

/*< private >*/

1076

SOMETHING_COUNT

1077

} Something;

1078

]]>

1079

</programlisting>

1080

</example>

1081

1082

<para>

1083

Use <code>/*< private >*/</code> before the private enum values

1084

you want to hide. Use <code>/*< public >*/</code> for the reverse

1085

behaviour.

1086

</para>

1087

1088

</sect2>

1089

</sect1>

1090

1091

1092

<title>ઉપયોગી DocBook ટૅગ</title>

1093

1094

<para>અહિંયા અમુક DocBook ટૅગ છે કે જે મોટાભાગનાં ઉપયોગી છે જ્યારે કોડનું દસ્તાવેજ કરી રહ્યા છે.</para>

1095

1096

<para>

1097

To link to another section in the GTK docs:

1098

1099

1100

1101

<![CDATA[

1102

1103

]]>

1104

</programlisting>

1105

</informalexample>

1106

The linkend is the SGML/XML id on the top item of the page you want to link to.

1107

For most pages this is currently the part ("gtk", "gdk", "glib") and then

1108

the page title ("Hash Tables"). For widgets it is just the class name.

1109

Spaces and underscores are converted to '-' to conform to SGML/XML.

1110

</para>

1111

1112

<para>બહારનાં વિધેયનો સંદર્ભ લેવા માટે, દા.ત. મૂળભૂત C વિધેય: <informalexample>

1113

1114

<![CDATA[

1115

1116

]]>

1117

</programlisting>

1118

</informalexample></para>

1119

1120

<para>

1121

To include example code:

1122

1123

1124

<![CDATA[

1125

1126

<title>Using a GHashTable.</title>

1127

1128

...

1129

</programlisting>

1130

</example>

1131

]]>

1132

</programlisting>

1133

</informalexample>

1134

or possibly this, for very short code fragments which don't need a title:

1135

1136

1137

<![CDATA[

1138

1139

1140

...

1141

</programlisting>

1142

</informalexample>

1143

]]>

1144

</programlisting>

1145

</informalexample>

1146

For the latter GTK-Doc also supports an abbreviation:

1147

<![CDATA[

1148

|[

1149

...

1150

]|

1151

]]>

1152

</para>

1153

1154

<para>બુલેટ થયેલ યાદીઓને સમાવવા માટે: <informalexample>

1155

1156

<![CDATA[

1157

1158

1159

<para>

1160

...

1161

</para>

1162

</listitem>

1163

1164

<para>

1165

...

1166

</para>

1167

</listitem>

1168

</itemizedlist>

1169

]]>

1170

</programlisting>

1171

</informalexample></para>

1172

1173

<para>

1174

To include a note which stands out from the text:

1175

1176

1177

<![CDATA[

1178

<note>

1179

<para>

1180

Make sure you free the data after use.

1181

</para>

1182

</note>

1183

]]>

1184

</programlisting>

1185

</informalexample>

1186

</para>

1187

1188

<para>પ્રકારનો સંદર્ભ લેવા માટે: <informalexample>

1189

1190

<![CDATA[

1191

<type>unsigned char</type>

1192

]]>

1193

</programlisting>

1194

</informalexample></para>

1195

1196

<para>બહારનાં બંધારણનો સંદર્ભ લેવા માટે (GTK દસ્તાવેજોમાં વર્ણવેલ નથી): <informalexample>

1197

1198

<![CDATA[

1199

<structname>XFontStruct</structname>

1200

]]>

1201

</programlisting>

1202

</informalexample></para>

1203

1204

<para>બંધારણનાં ક્ષેત્રનો સંદર્ભ લેવા માટે: <informalexample>

1205

1206

<![CDATA[

1207

1208

]]>

1209

</programlisting>

1210

</informalexample></para>

1211

1212

<para>

1213

To refer to a class name, we could possibly use:

1214

1215

1216

<![CDATA[

1217

<classname>GtkWidget</classname>

1218

]]>

1219

</programlisting>

1220

</informalexample>

1221

but you'll probably be using #GtkWidget instead (to automatically create

1222

a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).

1223

</para>

1224

1225

<para>લખાણ પર ભાર મૂકવા માટે: <informalexample>

1226

1227

<![CDATA[

1228

<emphasis>This is important</emphasis>

1229

]]>

1230

</programlisting>

1231

</informalexample></para>

1232

1233

<para>ફાઇલનામો વાપરવા માટે: <informalexample>

1234

1235

<![CDATA[

1236

<filename>/home/user/documents</filename>

1237

]]>

1238

</programlisting>

1239

</informalexample></para>

1240

1241

<para>કીઓ વાપરવાનું સંદર્ભ લેવા માટે: <informalexample>

1242

1243

<![CDATA[

1244

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>

1245

]]>

1246

</programlisting>

1247

</informalexample></para>

1248

1249

</sect1>

1250

</chapter>

1251

1252

1253

<title>વધારાની ફાઇલોને ભરી રહ્યા છે</title>

1254

1255

<para>

1256

There are a couple of extra files, that need to be maintained along with

1257

the inline source code comments:

1258

<filename><package>.types</filename>,

1259

<filename><package>-docs.xml</filename> (in the past .sgml),

1260

<filename><package>-sections.txt</filename>.

1261

</para>

1262

1263

1264

<title>ફાઇલોનાં પ્રકારોને સુધારી રહ્યા છે</title>

1265

1266

<para>જો તમે લાઇબ્રેરી અથવા કાર્યક્રમ એ GtkObjects/GObjects ને સમાવે તો, તમે દસ્તાવેજીકરણમાં બતાવેલ શ્રેણીમાં તેનાં સંકેતો, દલીલો/પરિમાણો અને સ્થાનને ઇચ્છો તો. <filename><package>.types</filename> ફાઇલ ની અંદર તેનાં સમાવેશ સાથે <function>xxx_get_type</function> વિધેયોની ભેગી યાદીમાં તમારે બધાને કરવાની જરૂર છે.</para>

1267

1268

<para>

1269

<example><title>Example types file snippet</title>

1270

1271

<![CDATA[

1272

#include <gtk/gtk.h>

1273

1274

gtk_accel_label_get_type

1275

gtk_adjustment_get_type

1276

gtk_alignment_get_type

1277

gtk_arrow_get_type

1278

]]>

1279

</programlisting>

1280

</example>

1281

</para>

1282

1283

<para>જ્યાં સુધી GTK-Doc 1.8 <application>gtkdoc-scan</application> એ તમારા માટે આ યાદી ઉત્પન્ન કરી શકે, <filename>Makefile.am</filename> માં SCAN_OPTIONS માટે "--rebuild-types" ને ખાલી ઉમેરો. જો તમે આ હેતુ થી વાપરો તો તમારે ફાઇલનાં પ્રકારોની યાદી કરવી જોઇએ નહિ અથવા આવૃત્તિ નિયંત્રણ હેઠળ તે હોવુ જોઇએ નહિં.</para>

1284

1285

</sect1>

1286

1287

1288

<title>મુખ્ય દસ્તાવેજને સુધારી રહ્યા છે</title>

1289

1290

<para>

1291

GTK-Doc produces documentation in DocBook SGML/XML. When processing the

1292

inline source comments, the GTK-Doc tools generate one documentation

1293

page per class or module as a separate file. The master document

1294

includes them and place them in an order.

1295

</para>

1296

1297

<para>

1298

While GTK-Doc creates a template master document for you, later run will

1299

not touch it again. This means that one can freely structure the

1300

documentation. That includes grouping pages and adding extra pages.

1301

GTK-Doc has now a test suite, where also the master-document is recreated from scratch.

1302

Its a good idea to look at this from time to time to see if there are some new goodies

1303

introduced there.

1304

</para>

1305

1306

<tip>

1307

<para>

1308

Do not create tutorials as extra documents. Just write extra chapters.

1309

The benefit of directly embedding the tutorial for your library into

1310

the API documentation is that it is easy to link for the tutorial to

1311

symbol documentation. Apart chances are higher that the tutorial gets

1312

updates along with the library.

1313

</para>

1314

</tip>

1315

1316

<para>

1317

So what are the things to change inside the master document? For a start

1318

is only a little. There are some placeholders (text in square brackets)

1319

there which you should take care of.

1320

</para>

1321

1322

<para>

1323

<example><title>મુખ્ય દસ્તાવેજ મથાળુ</title>

1324

1325

<![CDATA[

1326

1327

<title>MODULENAME Reference Manual</title>

1328

1329

for MODULENAME [VERSION]

1330

The latest version of this documentation can be found on-line at

1331

<ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.

1332

</releaseinfo>

1333

</bookinfo>

1334

1335

1336

<title>[Insert title here]</title>

1337

]]>

1338

</programlisting>

1339

</example>

1340

</para>

1341

1342

</sect1>

1343

1344

1345

<title>વિભાગ ફાઇલને સુધારી રહ્યા છે</title>

1346

1347

<para>

1348

The section file is used to organise the documentation output by

1349

GTK-Doc. Here one specifies which symbol belongs to which module or

1350

class and control the visibility (public or private).

1351

</para>

1352

1353

<para>

1354

The section file is a plain test file with xml like syntax (using tags).

1355

Blank lines are ignored and lines starting with a '#' are treated as

1356

comment lines.

1357

</para>

1358

1359

<para>

1360

The <FILE> ... </FILE> tag is used to specify the file name,

1361

without any suffix. For example, using '<FILE>gnome-config</FILE>'

1362

will result in the section declarations being output in the template

1363

file <filename>tmpl/gnome-config.sgml</filename>, which will be

1364

converted into the DocBook SGML/XML file <filename>sgml/gnome-config.sgml</filename>

1365

or .DocBook XML file <filename>xml/gnome-config.xml</filename>.

1366

(The name of the html file is based on the module name and the section

1367

title, or for gobjects it is based on the gobjects class name converted

1368

to lower case).

1369

</para>

1370

1371

<para>

1372

The <TITLE> ... </TITLE> tag is used to specify the title of

1373

the section. It is only useful before the templates (if used) are

1374

initially created, since the title set in the template file overrides

1375

this. Also if one uses SECTION comment in the sources, this is obsolete.

1376

</para>

1377

1378

<para>

1379

You can group items in the section by using the <SUBSECTION> tag.

1380

Currently it outputs a blank line between subsections in the synopsis

1381

section.

1382

You can also use <SUBSECTION Standard> for standard GObject

1383

declarations (e.g. the functions like g_object_get_type and macros like

1384

G_OBJECT(), G_IS_OBJECT() etc.).

1385

Currently these are left out of the documentation.

1386

You can also use <SUBSECTION Private> for private declarations

1387

which will not be output (It is a handy way to avoid warning messages

1388

about unused declarations.).

1389

If your library contains private types which you don't want to appear in

1390

the object hierarchy and the list of implemented or required interfaces,

1391

add them to a Private subsection.

1392

Wheter you would place GObject and GObjectClass like structs in public

1393

or Standard section depends if they have public entries (variables,

1394

vmethods).

1395

</para>

1396

1397

<para>

1398

You can also use <INCLUDE> ... </INCLUDE> to specify the

1399

#include files which are shown in the synopsis sections.

1400

It contains a comma-separate list of #include files, without the angle

1401

brackets. If you set it outside of any sections, it acts for all

1402

sections until the end of the file. If you set it within a section, it

1403

only applies to that section.

1404

</para>

1405

1406

</sect1>

1407

1408

</chapter>

1409

1410

1411

<title>પરિણામને નિયંત્રણ કરી રહ્યા છે</title>

1412

1413

<para>

1414

A GTK-Doc run generates report files inside the documentation directory.

1415

The generated files are named:

1416

<filename><package>-undocumented.txt</filename>,

1417

<filename><package>-undeclared.txt</filename> and

1418

<filename><package>-unused.txt</filename>.

1419

All those are plain text files that can be viewed and postprocessed easily.

1420

</para>

1421

1422

<para>

1423

The <filename><package>-undocumented.txt</filename> file starts with

1424

the documentation coverage summary. Below are two sections divided by

1425

blank lines. The first section lists undocumented or incomplete symbols.

1426

The second section does the same for section docs. Incomplete entries are

1427

those, which have documentation, but where e.g. a new parameter has been

1428

added.

1429

</para>

1430

1431

<para><filename><package>-sections.txt</filename> માં આપેલ સંકેતોને <filename><package>-undeclared.txt</filename> એ યાદી કરે છે પરંતુ સ્ત્રોતોમાં મળ્યુ નથી. ચકાસો જો તેઓને દૂર કરી દેવામાં આવી રહ્યુ છે અથવા જો તેઓની જોડણી થયેલ નથી.</para>

1432

1433

<para><filename><package>-unused.txt</filename> ફાઇલ એ સંકેત નામોની યાદી કરે છે, જ્યાં GTK-Doc સ્કેનર એ દસ્તાવેજીકરણને શોધ્યુ હતુ, પરંતુ જાણતા નથી ક્યાં તેને મૂકવાનું. આનો મતલબ એ કે સંકેતને હજુ <filename><package>-sections.txt</filename> ફાઇલ માં ઉમેરી દેવામાં આવ્યા નથી.</para>

1434

1435

<tip>

1436

<para>સક્રિય કરો અથવા Makefile.am માં <option>TESTS=$(GTKDOC_CHECK)</option> વાક્ય ને ઉમેરો. જો ઓછામાં ઓછુ GTK-Doc 1.9 સ્થાપિત થયેલ હોય તો, આ <command>make check</command> ને ચલાવવા દરમ્યાન સેનિટિ ચકાસણીને ચલાવશે.</para>

1437

</tip>

1438

1439

<para>

1440

One can also look at the files produced by the source code scanner:

1441

<filename><package>-decl-list.txt</filename> and

1442

<filename><package>-decl.txt</filename>. The first one can be

1443

compared with the section file if that is manualy maintained. The second

1444

lists all declarations fromt he headers If a symbol is missing one could

1445

check if this file contains it.

1446

</para>

1447

1448

<para>જો પ્રોજેક્ટ એ GObject આધારિત હોય તો, એક ઓબ્જેક્ટ સ્કેનર દ્દારા ઉત્પન્ન થયેલ ફાઇલોમાં પણ જોઇ શકો છો: <filename><package>.args.txt</filename>, <filename><package>.hierarchy.txt</filename>, <filename><package>.interfaces.txt</filename>, <filename><package>.prerequisites.txt</filename> અને <filename><package>.signals.txt</filename>. જો ત્યાં પેલાનાં કોઇપણમાં ગુમ થયેલ સંકેતો છે તો, આગળ પૃથ્થકરણ માટે અંતર્માધ્યમ સ્કેનર ફાઇલને રાખવા માટે એકજણ gtkdoc ને પૂછી શકે છે, પરંતુ <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> તરીકે તેને ચલાવી રહ્યા છે.</para>

1449

</chapter>

1450

1451

1452

<title>Documenting other interfaces</title>

1453

1454

<para>

1455

So far we have been using GTK-Doc to document the API of code. The next

1456

sections contain suggestions how the tools can be used to document other

1457

interfaces too.

1458

</para>

1459

1460

1461

<title>Commandline options and man pages</title>

1462

1463

<para>

1464

As one can generate man pages for a docbook refentry as well, it sounds

1465

like a good idea to use it for that purpose. This way the interface is

1466

part of the reference and one gets the man-page for free.

1467

</para>

1468

1469

1470

<title>Document the tool</title>

1471

1472

<para>

1473

Create one refentry file per tool. Following

1474

1475

<filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml

1476

tags that should be used and can look at generated file in the xml

1477

subdirectory as well as examples e.g. in glib.

1478

</para>

1479

</sect2>

1480

1481

1482

<title>Adding the extra configure check</title>

1483

1484

<para>

1485

<example><title>Extra configure checks</title>

1486

1487

<![CDATA[

1488

AC_ARG_ENABLE(man,

1489

[AC_HELP_STRING([--enable-man],

1490

[regenerate man pages from Docbook [default=no]])],enable_man=yes,

1491

enable_man=no)

1492

1493

AC_PATH_PROG([XSLTPROC], [xsltproc])

1494

AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)

1495

]]>

1496

</programlisting>

1497

</example>

1498

</para>

1499

</sect2>

1500

1501

1502

<title>Adding the extra makefile rules</title>

1503

1504

<para>

1505

<example><title>Extra configure checks</title>

1506

1507

<![CDATA[

1508

man_MANS = \

1509

meeper.1

1510

1511

if ENABLE_GTK_DOC

1512

if ENABLE_MAN

1513

1514

%.1 : %.xml

1515

@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<

1516

1517

endif

1518

endif

1519

1520

BUILT_EXTRA_DIST = $(man_MANS)

1521

EXTRA_DIST += meep.xml

1522

]]>

1523

</programlisting>

1524

</example>

1525

</para>

1526

</sect2>

1527

</sect1>

1528

1529

1530

<title>DBus interfaces</title>

1531

1532

<para>

1533

(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,

1534

http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)

1535

</para>

1536

</sect1>

1537

1538

</chapter>

1539

1540

1541

<title>Frequently asked questions</title>

1542

1543

1544

<?dbhtml list-presentation="list"?>

1545

1546

1547

1548

1549

<seg>ઓબ્જેક્ટો એ ફાઇલ <function>xxx_get_type()</function> માં દાખલ કરી દેવામાં આવ્યુ નથી <filename><package>.types</filename></seg>

1550

</seglistitem>

1551

1552

1553

<seg><filename><package>-sections.txt</filename> ફાઇલમાં ગુમ થયેલ અથવા ખોટુ નામ (જુઓ <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">વિગતવાર</ulink>).</seg>

1554

</seglistitem>

1555

1556

<seg>Damn, I have still no class hierarchy.</seg>

1557

<seg>

1558

Is the object name (name of the instance struct, e.g. <type>GtkWidget</type>)

1559

part of the normal section (don't put this into Standard or Private

1560

subsections).

1561

</seg>

1562

</seglistitem>

1563

1564

<seg>સંકેત અનુક્રમણિકા નથી.</seg>

1565

<seg>

1566

Does the <filename><package>-docs.{xml,sgml}</filename> contain a

1567

index that xi:includes the generated index?

1568

</seg>

1569

</seglistitem>

1570

1571

<seg>સંકેતો એ તેનાં દસ્તાવેજ-વિભાગમાં કડી થયેલ નથી.</seg>

1572

<seg>

1573

Is the doc-comment using the correct markup (added #,% or ())?

1574

Check if the gtkdoc-fixxref warns about unresolvable xrefs.

1575

</seg>

1576

</seglistitem>

1577

1578

<seg>નવો વર્ગ એ દસ્તાવેજોમાં દેખાતો નથી.</seg>

1579

<seg>શું તે નવુ પાનું xi છે: <filename><package>-docs.{xml,sgml}</filename> માંથી સમાવેલ છે.</seg>

1580

</seglistitem>

1581

1582

<seg>નવો સંકેત એ દસ્તાવેજોમાં દેખાતુ નથી.</seg>

1583

<seg>

1584

Is the doc-comment properly formatted. Check for spelling mistakes in

1585

the begin of the comment. Check if the gtkdoc-fixxref warns about

1586

unresolvable xrefs. Check if the symbol is correctly listed in the

1587

<filename><package>-sections.txt</filename> in a public subsection.

1588

</seg>

1589

</seglistitem>

1590

1591

<seg>પ્રકાર એ વર્ગ શ્રેણામાંથી ગુમ થયેલ છે.</seg>

1592

<seg>

1593

If the type is listed in <filename><package>.hierarchy</filename>

1594

but not in <filename>xml/tree_index.sgml</filename> then double check

1595

that the type is correctly placed in the <filename><package>-sections.txt</filename>.

1596

If the type instance (e.g. <type>GtkWidget</type>) is not listed or

1597

incidentialy makred private it will not be shown.

1598

</seg>

1599

</seglistitem>

1600

1601

<seg>બધા gobject ઍનોટેશન માટે foldoc કડીઓ મને મળે છે.</seg>

1602

<seg>ચકાસો કે જે <filename>xml/annotation-glossary.xml</filename> એ xi છે: <filename><package>-docs.{xml,sgml}</filename> માંથી સમાવેલ છે.</seg>

1603

</seglistitem>

1604

1605

1606

1607

<seg>સ્ત્રોત કોડ ટિપ્પણી બ્લોકમાં પરિમાણ વર્ણવેલ છે પરંતુ અસ્તિત્વ ધરાવતુ નથી</seg>

1608

<seg>ચકાસો જો મથાળામાં પ્રોટોટાઇપ પાસે સ્ત્રોતમાં વિવિધ પરિમાણ નામો છે.</seg>

1609

</seglistitem>

1610

1611

1612

1613

<seg>multiple "IDs" for constraint linkend: XYZ</seg>

1614

<seg>સંકેત XYZ એ <filename><package>-sections.txt</filename> ફાઇલમાં બે વાર દેખાય છે.</seg>

1615

</seglistitem>

1616

1617

<seg>Element typename in namespace '' encountered in para, but no template matches.</seg>

1618

<seg/>

1619

</seglistitem>

1620

</segmentedlist>

1621

</chapter>

1622

1623

1624

<title>Tools related to gtk-doc</title>

1625

1626

<para>

1627

GtkDocPlugin - a <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>

1628

integration plugin, that adds api docs to a trac site and integrates with

1629

the trac search.

1630

</para>

1631

<para>

1632

Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since

1633

tags in the api to determine the minimum required version.

1634

</para>

1635

1636

</chapter>

1637

1638

1639

<!--

1640

The GNU Free Documentation License 1.1 in DocBook

1641

Markup by Eric Baudais <baudais@okstate.edu>

1642

Maintained by the GNOME Documentation Project

1643

http://developer.gnome.org/projects/gdp

1644

Version: 1.0.1

1645

Last Modified: Nov 16, 2000

1646

-->

1647

1648

1649

1650

<releaseinfo>Version 1.1, March 2000</releaseinfo>

1651

1652

<year>2000</year><holder>Free Software Foundation, Inc.</holder>

1653

</copyright>

1654

1655

<para><address>Free Software Foundation, Inc. <street>51 Franklin Street, Suite 330</street>, <city>Boston</city>, <state>MA</state><postcode>02110-1301</postcode><country>USA</country></address> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</para>

1656

</legalnotice>

1657

</appendixinfo>

1658

<title>GNU Free Documentation License</title>

1659

1660

1661

<title>0. PREAMBLE</title>

1662

<para>

1663

The purpose of this License is to make a manual, textbook, or

1664

other written document <quote>free</quote> in the sense of

1665

freedom: to assure everyone the effective freedom to copy and

1666

redistribute it, with or without modifying it, either

1667

commercially or noncommercially. Secondarily, this License

1668

preserves for the author and publisher a way to get credit for

1669

their work, while not being considered responsible for

1670

modifications made by others.

1671

</para>

1672

1673

<para>

1674

This License is a kind of <quote>copyleft</quote>, which means

1675

that derivative works of the document must themselves be free in

1676

the same sense. It complements the GNU General Public License,

1677

which is a copyleft license designed for free software.

1678

</para>

1679

1680

<para>

1681

We have designed this License in order to use it for manuals for

1682

free software, because free software needs free documentation: a

1683

free program should come with manuals providing the same

1684

freedoms that the software does. But this License is not limited

1685

to software manuals; it can be used for any textual work,

1686

regardless of subject matter or whether it is published as a

1687

printed book. We recommend this License principally for works

1688

whose purpose is instruction or reference.

1689

</para>

1690

</sect1>

1691

1692

<title>1. APPLICABILITY AND DEFINITIONS</title>

1693

1694

This License applies to any manual or other work that contains a

1695

notice placed by the copyright holder saying it can be

1696

distributed under the terms of this License. The

1697

<quote>Document</quote>, below, refers to any such manual or

1698

work. Any member of the public is a licensee, and is addressed

1699

as <quote>you</quote>.

1700

</para>

1701

1702

1703

A <quote>Modified Version</quote> of the Document means any work

1704

containing the Document or a portion of it, either copied

1705

verbatim, or with modifications and/or translated into another

1706

language.

1707

</para>

1708

1709

1710

A <quote>Secondary Section</quote> is a named appendix or a

1711

front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively

1712

with the relationship of the publishers or authors of the

1713

Document to the Document's overall subject (or to related

1714

matters) and contains nothing that could fall directly within

1715

that overall subject. (For example, if the Document is in part a

1716

textbook of mathematics, a Secondary Section may not explain any

1717

mathematics.) The relationship could be a matter of historical

1718

connection with the subject or with related matters, or of

1719

legal, commercial, philosophical, ethical or political position

1720

regarding them.

1721

</para>

1722

1723

1724

The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles

1725

are designated, as being those of Invariant Sections, in the

1726

notice that says that the <link linkend="fdl-document">Document</link> is released under this

1727

License.

1728

</para>

1729

1730

1731

The <quote>Cover Texts</quote> are certain short passages of

1732

text that are listed, as Front-Cover Texts or Back-Cover Texts,

1733

in the notice that says that the <link linkend="fdl-document">Document</link> is released under this

1734

License.

1735

</para>

1736

1737

1738

A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable

1739

copy, represented in a format whose specification is available

1740

to the general public, whose contents can be viewed and edited

1741

directly and straightforwardly with generic text editors or (for

1742

images composed of pixels) generic paint programs or (for

1743

drawings) some widely available drawing editor, and that is

1744

suitable for input to text formatters or for automatic

1745

translation to a variety of formats suitable for input to text

1746

formatters. A copy made in an otherwise Transparent file format

1747

whose markup has been designed to thwart or discourage

1748

subsequent modification by readers is not Transparent. A copy

1749

that is not <quote>Transparent</quote> is called

1750

<quote>Opaque</quote>.

1751

</para>

1752

1753

<para>

1754

Examples of suitable formats for Transparent copies include

1755

plain ASCII without markup, Texinfo input format, LaTeX input

1756

format, SGML or XML using a publicly available DTD, and

1757

standard-conforming simple HTML designed for human

1758

modification. Opaque formats include PostScript, PDF,

1759

proprietary formats that can be read and edited only by

1760

proprietary word processors, SGML or XML for which the DTD

1761

and/or processing tools are not generally available, and the

1762

machine-generated HTML produced by some word processors for

1763

output purposes only.

1764

</para>

1765

1766

1767

The <quote>Title Page</quote> means, for a printed book, the

1768

title page itself, plus such following pages as are needed to

1769

hold, legibly, the material this License requires to appear in

1770

the title page. For works in formats which do not have any title

1771

page as such, <quote>Title Page</quote> means the text near the

1772

most prominent appearance of the work's title, preceding the

1773

beginning of the body of the text.

1774

</para>

1775

</sect1>

1776

1777

1778

<title>2. VERBATIM COPYING</title>

1779

<para>

1780

You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either

1781

commercially or noncommercially, provided that this License, the

1782

copyright notices, and the license notice saying this License

1783

applies to the Document are reproduced in all copies, and that

1784

you add no other conditions whatsoever to those of this

1785

License. You may not use technical measures to obstruct or

1786

control the reading or further copying of the copies you make or

1787

distribute. However, you may accept compensation in exchange for

1788

copies. If you distribute a large enough number of copies you

1789

must also follow the conditions in <link linkend="fdl-section3">section 3</link>.

1790

</para>

1791

1792

<para>

1793

You may also lend copies, under the same conditions stated

1794

above, and you may publicly display copies.

1795

</para>

1796

</sect1>

1797

1798

1799

<title>3. COPYING IN QUANTITY</title>

1800

<para>

1801

If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,

1802

and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose

1803

the copies in covers that carry, clearly and legibly, all these

1804

Cover Texts: Front-Cover Texts on the front cover, and

1805

Back-Cover Texts on the back cover. Both covers must also

1806

clearly and legibly identify you as the publisher of these

1807

copies. The front cover must present the full title with all

1808

words of the title equally prominent and visible. You may add

1809

other material on the covers in addition. Copying with changes

1810

limited to the covers, as long as they preserve the title of the

1811

1812

conditions, can be treated as verbatim copying in other

1813

respects.

1814

</para>

1815

1816

<para>

1817

If the required texts for either cover are too voluminous to fit

1818

legibly, you should put the first ones listed (as many as fit

1819

reasonably) on the actual cover, and continue the rest onto

1820

adjacent pages.

1821

</para>

1822

1823

<para>

1824

If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,

1825

you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with

1826

each Opaque copy, or state in or with each Opaque copy a

1827

publicly-accessible computer-network location containing a

1828

complete Transparent copy of the Document, free of added

1829

material, which the general network-using public has access to

1830

download anonymously at no charge using public-standard network

1831

protocols. If you use the latter option, you must take

1832

reasonably prudent steps, when you begin distribution of Opaque

1833

copies in quantity, to ensure that this Transparent copy will

1834

remain thus accessible at the stated location until at least one

1835

year after the last time you distribute an Opaque copy (directly

1836

or through your agents or retailers) of that edition to the

1837

public.

1838

</para>

1839

1840

<para>

1841

It is requested, but not required, that you contact the authors

1842

of the <link linkend="fdl-document">Document</link> well before

1843

redistributing any large number of copies, to give them a chance

1844

to provide you with an updated version of the Document.

1845

</para>

1846

</sect1>

1847

1848

1849

<title>4. MODIFICATIONS</title>

1850

<para>

1851

You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of

1852

sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release

1853

the Modified Version under precisely this License, with the

1854

Modified Version filling the role of the Document, thus

1855

licensing distribution and modification of the Modified Version

1856

to whoever possesses a copy of it. In addition, you must do

1857

these things in the Modified Version:

1858

</para>

1859

1860

1861

1862

1863

1864

<para>

1865

Use in the <link linkend="fdl-title-page">Title

1866

Page</link> (and on the covers, if any) a title distinct

1867

from that of the <link linkend="fdl-document">Document</link>, and from those of

1868

previous versions (which should, if there were any, be

1869

listed in the History section of the Document). You may

1870

use the same title as a previous version if the original

1871

publisher of that version gives permission.

1872

</para>

1873

</formalpara>

1874

</listitem>

1875

1876

1877

1878

1879

<para>

1880

List on the <link linkend="fdl-title-page">Title

1881

Page</link>, as authors, one or more persons or entities

1882

responsible for authorship of the modifications in the

1883

1884

together with at least five of the principal authors of

1885

the <link linkend="fdl-document">Document</link> (all of

1886

its principal authors, if it has less than five).

1887

</para>

1888

</formalpara>

1889

</listitem>

1890

1891

1892

1893

1894

<para>

1895

State on the <link linkend="fdl-title-page">Title

1896

Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the

1897

publisher.

1898

</para>

1899

</formalpara>

1900

</listitem>

1901

1902

1903

1904

1905

<para><link linkend="fdl-document">દસ્તાવેજ</link> ની કોપીરાઇટ બધી સૂચનાઓને સાચવો.</para>

1906

</formalpara>

1907

</listitem>

1908

1909

1910

1911

1912

<para>

1913

Add an appropriate copyright notice for your modifications

1914

adjacent to the other copyright notices.

1915

</para>

1916

</formalpara>

1917

</listitem>

1918

1919

1920

1921

1922

<para>

1923

Include, immediately after the copyright notices, a

1924

license notice giving the public permission to use the

1925

1926

the terms of this License, in the form shown in the

1927

Addendum below.

1928

</para>

1929

</formalpara>

1930

</listitem>

1931

1932

1933

1934

1935

<para>

1936

Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and

1937

required <link linkend="fdl-cover-texts">Cover

1938

Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.

1939

</para>

1940

</formalpara>

1941

</listitem>

1942

1943

1944

1945

1946

<para>આ લાઇસન્સની ચેતવણી ન થયેલ નકલને સમાવો.</para>

1947

</formalpara>

1948

</listitem>

1949

1950

1951

1952

1953

<para>

1954

Preserve the section entitled <quote>History</quote>, and

1955

its title, and add to it an item stating at least the

1956

title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version </link>as given on

1957

the <link linkend="fdl-title-page">Title Page</link>. If

1958

there is no section entitled <quote>History</quote> in the

1959

1960

stating the title, year, authors, and publisher of the

1961

Document as given on its Title Page, then add an item

1962

describing the Modified Version as stated in the previous

1963

sentence.

1964

</para>

1965

</formalpara>

1966

</listitem>

1967

1968

1969

1970

1971

<para>

1972

Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access

1973

to a <link linkend="fdl-transparent">Transparent</link>

1974

copy of the Document, and likewise the network locations

1975

given in the Document for previous versions it was based

1976

on. These may be placed in the <quote>History</quote>

1977

section. You may omit a network location for a work that

1978

was published at least four years before the Document

1979

itself, or if the original publisher of the version it

1980

refers to gives permission.

1981

</para>

1982

</formalpara>

1983

</listitem>

1984

1985

1986

1987

1988

<para>

1989

In any section entitled <quote>Acknowledgements</quote> or

1990

<quote>Dedications</quote>, preserve the section's title,

1991

and preserve in the section all the substance and tone of

1992

each of the contributor acknowledgements and/or

1993

dedications given therein.

1994

</para>

1995

</formalpara>

1996

</listitem>

1997

1998

1999

2000

2001

<para>

2002

Preserve all the <link linkend="fdl-invariant">Invariant

2003

Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their

2004

text and in their titles. Section numbers or the

2005

equivalent are not considered part of the section titles.

2006

</para>

2007

</formalpara>

2008

</listitem>

2009

2010

2011

2012

2013

<para>

2014

Delete any section entitled

2015

<quote>Endorsements</quote>. Such a section may not be

2016

included in the <link linkend="fdl-modified">Modified

2017

Version</link>.

2018

</para>

2019

</formalpara>

2020

</listitem>

2021

2022

2023

2024

2025

<para>

2026

Do not retitle any existing section as

2027

<quote>Endorsements</quote> or to conflict in title with

2028

any <link linkend="fdl-invariant">Invariant

2029

Section</link>.

2030

</para>

2031

</formalpara>

2032

</listitem>

2033

</itemizedlist>

2034

2035

<para>

2036

If the <link linkend="fdl-modified">Modified Version</link>

2037

includes new front-matter sections or appendices that qualify as

2038

2039

contain no material copied from the Document, you may at your

2040

option designate some or all of these sections as invariant. To

2041

do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the

2042

Modified Version's license notice. These titles must be

2043

distinct from any other section titles.

2044

</para>

2045

2046

<para>

2047

You may add a section entitled <quote>Endorsements</quote>,

2048

provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various

2049

parties--for example, statements of peer review or that the text

2050

has been approved by an organization as the authoritative

2051

definition of a standard.

2052

</para>

2053

2054

<para>

2055

You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage

2056

of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of

2057

the list of <link linkend="fdl-cover-texts">Cover Texts</link>

2058

in the <link linkend="fdl-modified">Modified Version</link>.

2059

Only one passage of Front-Cover Text and one of Back-Cover Text

2060

may be added by (or through arrangements made by) any one

2061

entity. If the <link linkend="fdl-document">Document</link>

2062

already includes a cover text for the same cover, previously

2063

added by you or by arrangement made by the same entity you are

2064

acting on behalf of, you may not add another; but you may

2065

replace the old one, on explicit permission from the previous

2066

publisher that added the old one.

2067

</para>

2068

2069

<para>

2070

The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License

2071

give permission to use their names for publicity for or to

2072

assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.

2073

</para>

2074

</sect1>

2075

2076

2077

<title>5. COMBINING DOCUMENTS</title>

2078

<para>

2079

You may combine the <link linkend="fdl-document">Document</link>

2080

with other documents released under this License, under the

2081

terms defined in <link linkend="fdl-section4">section 4</link>

2082

above for modified versions, provided that you include in the

2083

combination all of the <link linkend="fdl-invariant">Invariant

2084

Sections</link> of all of the original documents, unmodified,

2085

and list them all as Invariant Sections of your combined work in

2086

its license notice.

2087

</para>

2088

2089

<para>

2090

The combined work need only contain one copy of this License,

2091

and multiple identical <link linkend="fdl-invariant">Invariant

2092

Sections</link> may be replaced with a single copy. If there are

2093

multiple Invariant Sections with the same name but different

2094

contents, make the title of each such section unique by adding

2095

at the end of it, in parentheses, the name of the original

2096

author or publisher of that section if known, or else a unique

2097

number. Make the same adjustment to the section titles in the

2098

list of Invariant Sections in the license notice of the combined

2099

work.

2100

</para>

2101

2102

<para>

2103

In the combination, you must combine any sections entitled

2104

<quote>History</quote> in the various original documents,

2105

forming one section entitled <quote>History</quote>; likewise

2106

combine any sections entitled <quote>Acknowledgements</quote>,

2107

and any sections entitled <quote>Dedications</quote>. You must

2108

delete all sections entitled <quote>Endorsements.</quote>

2109

</para>

2110

</sect1>

2111

2112

2113

<title>6. COLLECTIONS OF DOCUMENTS</title>

2114

<para>

2115

You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents

2116

released under this License, and replace the individual copies

2117

of this License in the various documents with a single copy that

2118

is included in the collection, provided that you follow the

2119

rules of this License for verbatim copying of each of the

2120

documents in all other respects.

2121

</para>

2122

2123

<para>

2124

You may extract a single document from such a collection, and

2125

dispbibute it individually under this License, provided you

2126

insert a copy of this License into the extracted document, and

2127

follow this License in all other respects regarding verbatim

2128

copying of that document.

2129

</para>

2130

</sect1>

2131

2132

2133

<title>7. AGGREGATION WITH INDEPENDENT WORKS</title>

2134

<para>

2135

A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with

2136

other separate and independent documents or works, in or on a

2137

volume of a storage or distribution medium, does not as a whole

2138

count as a <link linkend="fdl-modified">Modified Version</link>

2139

of the Document, provided no compilation copyright is claimed

2140

for the compilation. Such a compilation is called an

2141

<quote>aggregate</quote>, and this License does not apply to the

2142

other self-contained works thus compiled with the Document , on

2143

account of their being thus compiled, if they are not themselves

2144

derivative works of the Document. If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these

2145

copies of the Document, then if the Document is less than one

2146

quarter of the entire aggregate, the Document's Cover Texts may

2147

be placed on covers that surround only the Document within the

2148

aggregate. Otherwise they must appear on covers around the whole

2149

aggregate.

2150

</para>

2151

</sect1>

2152

2153

2154

<title>8. TRANSLATION</title>

2155

<para>

2156

Translation is considered a kind of modification, so you may

2157

distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with

2158

translations requires special permission from their copyright

2159

holders, but you may include translations of some or all

2160

Invariant Sections in addition to the original versions of these

2161

Invariant Sections. You may include a translation of this

2162

License provided that you also include the original English

2163

version of this License. In case of a disagreement between the

2164

translation and the original English version of this License,

2165

the original English version will prevail.

2166

</para>

2167

</sect1>

2168

2169

2170

<title>9. TERMINATION</title>

2171

<para>

2172

You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly

2173

provided for under this License. Any other attempt to copy,

2174

modify, sublicense or distribute the Document is void, and will

2175

automatically terminate your rights under this License. However,

2176

parties who have received copies, or rights, from you under this

2177

License will not have their licenses terminated so long as such

2178

parties remain in full compliance.

2179

</para>

2180

</sect1>

2181

2182

2183

<title>10. FUTURE REVISIONS OF THIS LICENSE</title>

2184

<para>The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>

2185

2186

<para>

2187

Each version of the License is given a distinguishing version

2188

number. If the <link linkend="fdl-document">Document</link>

2189

specifies that a particular numbered version of this License

2190

<quote>or any later version</quote> applies to it, you have the

2191

option of following the terms and conditions either of that

2192

specified version or of any later version that has been

2193

published (not as a draft) by the Free Software Foundation. If

2194

the Document does not specify a version number of this License,

2195

you may choose any version ever published (not as a draft) by

2196

the Free Software Foundation.

2197

</para>

2198

</sect1>

2199

2200

2201

<title>Addendum</title>

2202

<para>તમે લખેલ છે તે દસ્તાવેજમાં આ લાઇસન્સને વાપરવા માટે, દસ્તાવેજમાં લાઇસન્સની નકલને સમાવો અને નીચેનાં કોપીરાઇટ અને લાઇસન્સ સૂચનાઓને શીર્ષક પાનાં પછી મૂકો:</para>

2203

2204

2205

<para>Copyright YEAR YOUR NAME.</para>

2206

<para>

2207

Permission is granted to copy, distribute and/or modify this

2208

document under the terms of the GNU Free Documentation

2209

License, Version 1.1 or any later version published by the

2210

Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST

2211

THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,

2212

and with the <link linkend="fdl-cover-texts">Back-Cover

2213

Texts</link> being LIST. A copy of the license is included in

2214

the section entitled <quote>GNU Free Documentation

2215

License</quote>.

2216

</para>

2217

</blockquote>

2218

2219

<para>

2220

If you have no <link linkend="fdl-invariant">Invariant

2221

Sections</link>, write <quote>with no Invariant Sections</quote>

2222

instead of saying which ones are invariant. If you have no

2223

2224

<quote>no Front-Cover Texts</quote> instead of

2225

<quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.

2226

</para>

2227

2228

<para>

2229

If your document contains nontrivial examples of program code,

2230

we recommend releasing these examples in parallel under your

2231

choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public

2232

License</ulink>, to permit their use in free software.

2233

</para>

2234

</sect1>

2235

</appendix>

2236

2237

2238

2239

2240

2241

2242

2243

2244

</book>