From f25b178cfc9e2893c8695aaf61f340300731999f Mon Sep 17 00:00:00 2001 From: yunshi Date: Sun, 13 Mar 2016 22:05:38 +0100 Subject: [PATCH] docs.dev: improve hyperlink.rst after code review --- docs/dev/analysis/features/text/hyperlink.rst | 280 ++++++++++-------- 1 file changed, 164 insertions(+), 116 deletions(-) diff --git a/docs/dev/analysis/features/text/hyperlink.rst b/docs/dev/analysis/features/text/hyperlink.rst index 9a123fb03..667d0bd6c 100644 --- a/docs/dev/analysis/features/text/hyperlink.rst +++ b/docs/dev/analysis/features/text/hyperlink.rst @@ -2,53 +2,51 @@ Hyperlink ========= -Word allows hyperlinks to be placed in the document or existing objects to be -turned into hyperlinks. +Word allows hyperlinks to be placed in the document. -Hyperlinks can point to a named object or range within the current document or -to an external resource. Hyperlinks can contain multiple runs of text. +Hyperlink may link to a external location, for example, as an url. It may link to +a location within the document, for example, as a bookmark. These two cases are +handled differently. +Hyperlinks can contain multiple runs of text. Candidate protocol ------------------ +The hyperlink feature supports only external links today (03/2016). + Add a simple hyperlink with text and url: - >>> hyperlink = paragraph.add_hyperlink(text='Google', url='http://google.com') + >>> hyperlink = paragraph.add_hyperlink(text='Google', address='https://google.com') + >>> hyperlink + >>> hyperlink.text 'Google' - >>> hyperlink.url - 'http://google.com' - >>> hyperlink.anchor - None - >>> len(hyperlink.runs) - 1 + >>> hyperlink.address + 'https://google.com' + >>> hyperlink.runs + [] Add multiple runs to a hyperlink: - >>> hyperlink = paragraph.add_hyperlink(url='http://github.com') + >>> hyperlink = paragraph.add_hyperlink(address='https://github.com') >>> hyperlink.add_run('A') >>> hyperlink.add_run('formatted').italic = True >>> hyperlink.add_run('link').bold = True - >>> len(hyperlink.runs) - 3 - -Add a hyperlink pointing to a named range in the current document: + >>> hyperlink.runs + [, + , + ] - >>> hyperlink = paragraph.add_hyperlink(text='Section 1', anchor='section1') - >>> hyperlink.anchor - 'section1' - >>> hyperlink.url - None +Retrieve a paragraph's content: -Turning an existing object into a hyperlink: + >>> paragraph = document.add_paragraph('A plain paragraph having some ') + >>> paragraph.add_run('link such as ') + >>> paragraph.add_hyperlink(address='http://github.com', text='github') + >>> paragraph.iter_p_content(): + [, + ] - >>> existing_object = document.add_paragraph('Some text') - >>> hyperlink = existing_object.hyperlink(url='http://google.com') - >>> hyperlink.text - 'Some text' - >>> len(hyperlink.runs) - 1 Specimen XML @@ -56,109 +54,159 @@ Specimen XML .. highlight:: xml -A simple hyperlink to an external url:: - - - - - - - Google - - - -The relationship for the above url:: +External links +~~~~~~~~~~~~~~ - - - +An external link is specified by the attribute r:id. The location of the link +is defined in the relationships part of the document. -A hyperlink to an internal named range:: +A simple hyperlink to an external url:: - + - - - - Google + This is an external link to - + + + + + + Google + + + + + +The r:id="rId4" references the following relationship within the relationships +part for the document document.xml.rels.:: + + + + A hyperlink with multiple runs of text:: - + + + + + + + A + + + + + + + formatted + + + + + + + link + + + + + +Internal links +~~~~~~~~~~~~~~ + +An internal link, that link to a location in the document, do not have the r:id attribute +and is specified by the anchor attribute. +The value of the anchor attribute is the name of a bookmark in the document. + +Example:: + + - - - - A + This is an + + + + + + internal link + + + + + ... + + - - - - - formatted + This is text with a - - - - - - link - - - + + + bookmark + + + -Resources ---------- -* `Document Members (Word) on MSDN`_ -* `Hyperlink Members (Word) on MSDN`_ -* `Hyperlinks Members (Word) on MSDN`_ -* `Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN`_ -* `Hyperlink Class (OpenXML.Wordprocessing) on MSDN`_ - - -.. _Document Members (Word) on MSDN: - http://msdn.microsoft.com/en-us/library/office/ff840898.aspx - -.. _Hyperlink Members (Word) on MSDN: - http://msdn.microsoft.com/en-us/library/office/ff195109.aspx - -.. _Hyperlinks Members (Word) on MSDN: - http://msdn.microsoft.com/en-us/library/office/ff192421.aspx - -.. _Hyperlink Class (OpenXML.Office2010.CustomUI) on MSDN: - http://msdn.microsoft.com/en-us/library/documentformat.openxml.office2010.customui.hyperlink.aspx - -.. _Hyperlink Class (OpenXML.Wordprocessing) on MSDN: - http://msdn.microsoft.com/en-us/library/documentformat.openxml.wordprocessing.hyperlink.aspx - - -MS API ------- - -The Hyperlinks property on Document holds references to hyperlink -objects in the MS API. - -Hyperlinks contain the following properties: - -* Address -* SubAddress -* EmailSubject -* ExtraInfoRequired -* Range (In python-docx this would be the runs inside the hyperlink) -* ScreenTip -* Shape -* Target (where to open the hyperlink. e.g. "_blank", "_left", "_top", "_self", "_parent" etc) -* TextToDisplay -* Type (msoHyperlinkRange, msoHyperlinkShape or msoHyperlinkInlineShape) +Schema excerpt +-------------- +.. highlight:: xml -Spec references ---------------- +:: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -* 17.16.17 hyperlink (Hyperlink) -* 2.3.61 CT_Hyperlink