X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fdocumentation.rst;h=170dacdb77765a1baff2276f2ac07c2f4e8cb92a;hb=3004d3454192515f44fa4df1c4f64c9cde687913;hp=2cfb1a298c0d420a43ed6bfcf80f970f053ecd54;hpb=58c82067f1aeeb59301bf22dda1350853ff969da;p=dpdk.git diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index 2cfb1a298c..170dacdb77 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -34,7 +34,6 @@ The main directories that contain files related to documentation are shown below |-- testpmd_app_ug |-- rel_notes |-- nics - |-- xen |-- ... @@ -282,33 +281,21 @@ The additional guidelines below reiterate or expand upon those guidelines. Line Length ~~~~~~~~~~~ -* The recommended style for the DPDK documentation is to put sentences on separate lines. - This allows for easier reviewing of patches. - Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example:: +* Lines in sentences should be less than 80 characters and wrapped at + words. Multiple sentences which are not separated by a blank line are joined + automatically into paragraphs. - Here is an example sentence. - Long sentences over the limit shown below can be wrapped onto - a new line. - These three sentences will be joined into the same paragraph. +* Lines in literal blocks **must** be less than 80 characters since + they are not wrapped by the document formatters and can exceed the page width + in PDF documents. - This is a new paragraph, since it is separated from the - previous paragraph by a blank line. + Long literal command lines can be shown wrapped with backslashes. For + example:: - This would be rendered as follows: - - *Here is an example sentence. - Long sentences over the limit shown below can be wrapped onto - a new line. - These three sentences will be joined into the same paragraph.* - - *This is a new paragraph, since it is separated from the - previous paragraph by a blank line.* - - -* Long sentences should be wrapped at 120 characters +/- 10 characters. They should be wrapped at words. - -* Lines in literal blocks must by less than 80 characters since they aren't wrapped by the document formatters - and can exceed the page width in PDF documents. + testpmd -l 2-3 -n 4 \ + --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \ + -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \ + --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024 --txd=1024 Whitespace @@ -332,7 +319,7 @@ Whitespace Section Headers ~~~~~~~~~~~~~~~ -* Section headers should use the use the following underline formats:: +* Section headers should use the following underline formats:: Level 1 Heading =============== @@ -380,12 +367,11 @@ Lists #. Item one. - #. Item two is a long line that is wrapped and then indented - to match the start of the e first line. - #. Item two is a long line that is wrapped and then indented to match the start of the previous line. + #. Item three. + * Definition lists can be written with or without a bullet:: * Item one. @@ -458,7 +444,7 @@ Code and Literal block sections For long literal lines that exceed that limit try to wrap the text at sensible locations. For example a long command line could be documented like this and still work if copied directly from the docs:: - build/app/testpmd -c7 -n3 --vdev=net_pcap0,iface=eth0 \ + build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \ --vdev=net_pcap1,iface=eth1 \ -- -i --nb-cores=2 --nb-ports=2 \ --total-num-mbufs=2048 @@ -477,7 +463,7 @@ Images * `Inkscape `_ is the recommended graphics editor for creating the images. Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg`` - or ``ring-enqueue.svg``. + or ``ring-enqueue1.svg``. * The SVG images should include a copyright notice, as an XML comment.